Start with the actual tool result, current bot state and recent logs. A request acknowledgment means the server accepted the action, not that dependencies installed or Discord accepted the token. Avoid repeated writes or destructive retries while the outcome is uncertain. The dashboard troubleshooting guide covers the same runtime problems, and the agent uses those same guarded services.
Connection and authentication
A 401 response means the access token or OAuth grant is missing, malformed, expired or revoked. Check that the protected BH_API_TOKEN variable exists in the environment of the client or remote workspace that makes the connection. Do not paste the value into chat to debug it. A 403 can mean a missing scope, a foreign browser Origin, an unverified email or a banned account. Review account verification and the selected token scopes. Create another scoped token when necessary and revoke the old one. A missing tool can mean its required scope was not granted or your credential is restricted to existing bots. A 404 for a bot means it is not owned by your account, is excluded by the selected-bot restriction, or is deleted. The server does not reveal which case applies.
MCP needs initialization, its initialized notification, the returned session id and the negotiated protocol header. The supported protocol is . A missing session is rejected; an expired or unknown session needs a new initialization. Restart the connection after a backend restart. A 429 can mean a token budget or too many open sessions: close unused connections and honor Retry-After. When enabled, OAuth uses public-client registration, S256 PKCE and a one-hour grant bound to your selected bots. Sign in again after expiry or use a personal token with its own chosen expiry. The local forwarding package is not published, so use its reviewed Node script path rather than an npx registry command.
Bot token and intents
For Discord login errors, save the bot credential using set_bot_token, then restart after approval. Its value remains write-only, so inspect the configured indicator rather than asking the agent to read it back. Use a bot token from the application's Bot page, never a user token or application secret. Rotate a credential exposed in source or chat. If Discord closes the gateway for intents, compare your code with the application's enabled privileged intents. The minimal example uses only Guilds; message content or member events require separate configuration when your code needs them.
Dependencies and startup files
Deploy observes the runtime for up to ten seconds after the accepted power action. A running result confirms an observed process, so check get_logs for the Git commit and application readiness. A starting result means startup is still pending or unconfirmed; runtime_state is the latest observation and can still be offline. Check get_status and get_logs before issuing another deploy. An observed failure returns deploy_failed with a fixed reason, such as runtime_crashed or runtime_stopped_after_start. Start, stop and restart acknowledge dispatch; they do not claim a completed state change.
A missing-module error usually means a missing dependency declaration or the wrong startup file. Check MAIN_FILE, package.json or requirements.txt and filename case. Upload the manifest along with the code. The host installs dependencies during the normal start path. Do not upload local dependency folders as a workaround; reproduce your project from its manifest and lockfile. Runtime changes and file replacement need separate review in the dashboard.
Crash loops and disk full
The console and usage tools help distinguish configuration errors from memory pressure. Stop repeated automatic restart attempts while you inspect a recurring failure. The dashboard shows a repeated-crash hint, and the abuse stop still takes precedence over restart settings. Disk-full writes, uploads, extraction and starts are guarded by the current plan. Remove unnecessary generated files or choose a larger plan yourself in Billing. The agent cannot silently charge for an upgrade. Keep your own source and data backups before deleting files.
Held, expired or deleted bots
A 409 may indicate a staff hold, inactive entitlement, stale confirmation or a bot retained for recovery. Open that bot in the dashboard and review its current state. Free claims and renewals can need human browser checks. A retained bot's recovery deadline may end before a full day if its entitlement ends. Recovery uses the verified last backup and does not resume canceled billing. A failed or uncertain deletion must be checked before another request. Contact support through the dashboard if the native restore outcome cannot be established.
Read the agent quickstart, tool reference, API reference, complete deployment example and troubleshooting guide.
Still stuck? Contact support