# Documentation Page **Page:** kit/agent/chat-apps/troubleshooting [Download Raw Markdown](./kit/agent/chat-apps/troubleshooting.md) --- # Troubleshooting chat apps **Every chat app says what it is doing. Read its state first.** The state is in the agent's TUI (Bots tab, **⇄ Connect**, **Chat apps**) and in `state` of `GET /api/v1/agent/bots/{id}/channels/{cid}`. The last connection error is in `last_error` (`code`, `message`, `at`). When the chat app knows why it is in its state, `state_reason` says it (one of the reasons below). In the Hub, open **Bots**, select the Bot and open **Chat apps**. **State** shows each chat app's state, and **Needs you** names what to fix. Choose **Manage** to open its setup. To replace a token, use **Replace…** under **Bot token**, or use the **Replace the token** setup step if sign-in failed. Under **Settings**, use the switch named for the chat app to turn it off or on. **Pause all** and **Resume all** pause or resume the Bot's chat apps. ## States | State | What it means | What to do | |---|---|---| | `connecting` | The chat app is opening its connection to the platform. | Wait a few seconds. | | `connected` | Messages flow both ways. | Nothing. | | `awaiting_owner` | Nobody is paired as owner yet. With `dm_policy: owner`, nobody can talk to the Bot in a direct message. Group conversations follow `group_mode`. | Send the owner code to the bot in a direct message. Make a new one if it expired. | | `degraded` | The chat app has trouble connecting, receiving or saving, or has stopped running. Check `state_reason` and `last_error`. | Usually heals by itself: the chat app keeps retrying. If it stays, see the reasons below. If it stays with no reason, wait a minute. If it is still `degraded` with no reason, restart the agent. If it happens again, delete the chat app and connect it again. | | `standby` | Another chat app already runs this platform bot. This one waits. | Turn off or delete the other chat app, or delete this one. | | `conflict` | Another program reads the same bot, or a webhook was set on it. | Stop the other program. For a webhook: Turn the chat app off (`"enabled": false`), wait until its state is `paused`, then turn it on with `"enabled": true, "delete_webhook": true` in the same update. `delete_webhook` alone, on a chat app that is on, does nothing. | | `auth_failed` | The platform refused the token, or the token now belongs to another bot. Nothing retries. | Replace the token (`PUT …/channels/{cid}/credentials`, or **Replace keys** in the TUI). | | `paused` | The chat app is turned off, or chat apps are paused for the whole Bot. With the reason `not_running`, it is on but nothing runs it: see [Reasons](#reasons). | Turn it on (`enabled: true`, or **Resume** on the chat app in the TUI), or set `channels_paused: false` on the Bot. | | `realm_unserved` | The agent cannot confirm that its current login can serve this Bot. This can be temporary. | Wait a moment and read the state again. If it stays, sign the agent in again with a login that covers the Bot's realm. See [The Bot is gone from the list](#the-bot-is-gone-from-the-list). | | `stopping` | A change is waiting for the connection to close. | Wait. If it stays with the reason `stop_stuck`, restart the agent. | | `stopped` | The Bot is being deleted. | Nothing. | ## Reasons `state_reason` or `last_error.code` can carry one of these reasons: | Reason | Meaning | What to do | |---|---|---| | `unauthorized` | The platform refused the token. | Copy the token again, whole, and replace it. | | `binding_changed` | The token now belongs to another bot or another Slack workspace. | Replace it with a token of the original bot, or delete the chat app and connect the new bot as a new one. | | `missing_scope` | A Slack token lacks a scope. For the App-level token: it needs `connections:write`. | Add the scope, reinstall the Slack app, replace the token. | | `missing_intent` | Discord refused even the basic gateway intents (`auth_failed`). This should not happen. | Check the bot in the Developer Portal, then replace the token. | | `message_content_missing` | Discord did not grant Message Content. The chat app connected without it: in servers the Bot reads only messages that @mention it. | Turn on **Message Content Intent** in the Developer Portal, then turn the chat app off and on again, pause and resume the Bot's chat apps, or enter its token again. Waiting is not enough. The next connection asks for the intent; if it is still off, the chat app connects without it again. Until Discord grants the intent, `mention_only` cannot be set to `false`. | | `mismatched_app` | The two Slack tokens come from different apps. | Take both tokens from the same app. | | `app_unverified` | Slack did not say which app the Bot token belongs to. | Add `users:read`, reinstall the Slack app, and replace the Bot token. | | `unreachable` | The platform could not be reached. | Wait. The chat app retries. | | `rate_limited` | The platform slowed the chat app down, or a configured connection limit was reached. | Wait, and read `last_error` to identify the limit. Lower your own traffic if it keeps happening. | | `identity_in_use` | Another chat app runs this bot account (`standby`). | Run it from one place only. | | `other_poller` | Another program reads this Telegram bot (`conflict`). | Stop the other program. | | `webhook_set` | A webhook was set on this Telegram bot (`conflict`). | Turn the chat app off (`"enabled": false`), wait until its state is `paused`, then turn it on with `"enabled": true, "delete_webhook": true` in the same update. `delete_webhook` alone, on a chat app that is on, does nothing. | | `storage_failing` | The agent cannot save the chat app's data. | Check free disk space on the computer that runs the agent. | | `credentials_missing` | The saved token is gone. | Replace the saved credentials first, supplying both tokens for Slack. If replacement is refused because the credentials storage is missing, delete the chat app and connect it again. | | `not_running` | The chat app is on, but nothing runs it on this agent right now (`paused`). | Wait a few seconds and read the chat app again. If the Bot is suspended, resume it (see [The Bot is gone from the list](#the-bot-is-gone-from-the-list)). If it still shows, restart the agent. | | `channel_disabled` | The chat app is turned off (`paused`). | Turn it on (`"enabled": true`, or **Resume** on the chat app in the TUI). | | `bot_paused` | Chat apps are paused for the whole Bot (`paused`). | Set `channels_paused: false` on the Bot. | | `lock_unavailable` | The agent process on this computer cannot lock this chat app's bot account, so the chat app does not run (`degraded`). Either file locks do not work where the agent keeps its data, or a Discord chat app is missing its application or bot id. | Restart the agent. If it still shows on a Discord chat app, delete the chat app and connect it again. | | `lock_lost` | The chat app's lock was taken away while it ran, so another agent process may run this bot now. The chat app stopped (`degraded`) and does not start again by itself. | Make sure only one agent process runs this bot. Then turn the chat app off and on again (`"enabled": false`, then `"enabled": true`), or restart the agent. | | `stop_stuck` | The connection did not close in time (`stopping`). | Restart the agent. | | `gateway_refused` | Discord refused the gateway connection because of its shard, sharding requirement, API version or intents. | Check the bot's settings. Use the bot in fewer servers only when Discord requires sharding. If the settings do not explain the refusal, report the error. | | `missing_access` | Discord refused a channel. | Restore the bot's permission to read and send in that Discord channel. If the chat is `muted`, open the Bot's **Chat apps**, choose **Manage**, open **Chats**, and choose **Approve** for it (for a group, then confirm **Approve group**). Ask the sender to send the message again. | | `guild_unavailable` | A Discord server is briefly unavailable. | Wait. | | `payload_too_large` | An outgoing message, an incoming event or a platform response went over a size limit. | For an outgoing message, try a lower `part_chars` on this chat app. For an incoming event or response, read `last_error` for details; `part_chars` does not change incoming sizes. | | `chat_migrated` | The Telegram group became a supergroup with a new chat id. | Read the new id in `last_error.message`, then bind and approve the new chat. The approval does not carry over. | ## Errors when you set things up | Code | Status | What to do | |---|---|---| | `channel_credentials_invalid` | 422 | The platform refused the token, or could not be reached to check it. `reason` says why (table above). | | `channel_exists` | 409 | This Bot already has this platform bot. Use the existing chat app. | | `channel_identity_in_use` | 409 | Another chat app, of this Bot or another one, already runs this platform bot. Delete or turn off the other one first, or use another bot. | | `channel_conflict` | 409 | Read `details.reason`. For `webhook_set` (the Telegram bot has a webhook), send the create, or the update that turns the chat app on, again with `delete_webhook: true`. For `bot_paused`, first set `channels_paused: false` on the Bot, then send the request again with `delete_webhook: true`. | | `channel_identity_changed` | 409 | The new token belongs to another bot. Use a token of the same bot, or connect the other bot as a new chat app. | | `channels_exhausted` | 429 | The Bot has `max_channels` chat apps, or the chat app has `max_principals` people. A new pairing code is refused too (`channels_exhausted`) once the chat app already has `max_principals` people. Delete one first, or raise the limit. | | `owner_needs_pairing` | 409 | The first owner must pair through the platform with an owner code. Adding an owner by user id works only after that. | | `acknowledgement_required` | 422 | Approving a group needs `"acknowledge_group_readers": true`. | | `setting_invalid` | 422 | A setting has a bad value, or does not exist on this platform (`not_available`). `details.field` names it. | | `setting_conflict` | 422 | Two settings do not fit together. For example, approval cards can go to a group only when `decide_in_groups` is on (`gate_push_to_group`). | | `idempotency_key_reused` | 422 | The same `Idempotency-Key` came with another body. Use a new key. | | `idempotency_replay_gone` | 410 | The chat app this `Idempotency-Key` created was deleted since. Send the create with a new key. | | `idempotency_keys_exhausted` | 429 | Too many keyed creates are kept. Try later, or send the create without a key. | ## Other errors Any chat app request can also answer one of these: | Code | Status | What to do | |---|---|---| | `bad_request` | 400 | The request is malformed. `message` says what to fix. | | `invalid_realm` | 400 | The realm in `X-Hoody-Realm` or `?realm=` is not `global` or a realm id. Fix it. | | `realm_scope_unsupported` | 400 | Chat app requests take a realm only. Drop the other scope headers, or use the realm this agent is pinned to. | | `forbidden` | 403 | Hoody Kit programs are reached through their URLs only. Call the agent through its URL. | | `not_found` | 404 | Check the Bot id, the chat app id and the realm. A Bot that is [gone from the list](#the-bot-is-gone-from-the-list) also answers 404. | | `realm_blocked` | 409 | The agent's selected realm is not usable. Select a valid realm, or name one with `X-Hoody-Realm`. | | `bot_owned_elsewhere` | 409 | Another agent process on this computer serves this Bot, so nothing of it was read or changed. Wait the seconds in `Retry-After`, then try again, or use the agent that serves the Bot. `GET /api/v1/agent/bots` lists such a Bot with `owned_elsewhere: true`. If `details.reason` is `lock_unavailable`, the agent cannot lock the Bot's files on its storage: if it keeps failing, keep the agent's data on storage that supports file locks. | | `payload_too_large` | 413 | The request body is too big. Send less. | | `rate_limited` | 429 | Too many requests. Wait the seconds in `Retry-After`, then try again. | | `internal_error` | 500 | Something failed inside the agent. Try again. If it keeps failing, check the agent's logs. | | `restriction_unknown` | 503 | The agent could not read which realms your login covers. Try again in a moment. If it says to sign in again, do that. | | `service_unavailable` | 503 | The agent is busy or starting, or the Bot's chat apps are being handed over or their store is not available right now. Try again, after the seconds in `Retry-After` when it is set. For a change, read the chat app first: it may already be applied. For a delete, see [Delete a chat app](/kit/agent/chat-apps/#delete-a-chat-app). | ## The Bot is gone from the list A Bot is suspended when the account the agent is signed in with signs out, changes, or no longer covers the Bot's realm. A suspended Bot stops working, its chat apps stop, it is left out of the list, and its requests answer 404 `not_found`. Nothing is deleted. The Bot comes back on its own when the agent is signed in again with the same account, and that account covers the Bot's realm. To keep its Bots under the account signed in now, resume them. In the Hub, open **Bots** and choose **Resume** on the notice that says one or more Bots are paused after a sign-in change. In the TUI's Bots tab, choose **[ ⟳ Resume N ]** (or press `R`). Through the API, call `POST /api/v1/agent/bots/resume` (no body). The call resumes the suspended Bots of the agent's current realm, or of every realm the account covers with `?realm=all`, and its answer lists them in `resumed`. A 503 means a Bot could not be resumed right now and stays suspended: try again in a moment. ```bash hoody agent bots resume -c $COMPUTER_ID --realm all ``` `--realm all` resumes the suspended Bots of every realm the account covers. Leave it out to resume those of the agent's current realm. `--realm` is an option of `hoody` itself, so `hoody agent bots resume --help` does not list it. ```ts import { HoodyClient } from 'hoody-sdk'; const hoody = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const box = await hoody.withComputer(process.env.COMPUTER_ID!); const { data } = await box.agent.bots.resumeAll({ agentRealm: 'all' }); for (const bot of data.resumed) console.log(bot.id, bot.realm); ``` Without `agentRealm`, the call resumes the suspended Bots of the agent's current realm. ```bash curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/resume?realm=all" ``` If your computer's proxy permissions protect the agent, add the credential its group requires to the cURL example; see [proxy permissions](/foundation/proxy/permissions/). An agent pinned to one realm accepts only that realm, and answers `realm_scope_unsupported` to `all`. There, leave out `--realm all`, `agentRealm: 'all'` or `?realm=all`. ## Messages in the chat The chat app answers some messages itself: | Message | Meaning | |---|---| | I only talk with people the owner allows. Ask the owner for a pairing code. | The chat app's access settings do not allow your direct message. If you are not paired, ask the owner for a code. If you are, ask the owner to check your `chat` right and `dm_policy`. | | To pair, send only the pairing code, typed exactly as shown… | The code was mixed with other text or was not typed exactly as shown. Send only the code using plain digits and letters; use 0 and 1, never O, I or L. | | That code is not valid or has expired. | Ask for a new code. By default, 5 wrong codes refuse you for 60 minutes; `pairing_user_burn_tries` and `pairing_user_burn_minutes` change those limits. | | You are already paired. That code is meant for someone else, so it was not used. | Nothing to do. Pass the code on to the person it was made for. | | Send your pairing code in a direct message to me, not in a group. | Codes work in direct messages only. | | Slow down: too many messages. Try again in a moment. | A [message limit](/kit/agent/chat-apps/security/#message-limits) was reached. | | Message too long: at most … bytes. | Shorten it, or send it in parts. | | I can only read text messages for now. Please type your message. | An allowed sender sent media without text. In a group, the message must address the Bot. Type the message instead; the notice is limited to once an hour. | | I held back a reply because it looked like it contained a secret… | Read the answer in the session. | | I do not take part in group chats. | Groups are off (`group_mode: off`). | | This group is not on my list. Ask the owner to add it. | The group must be added to `allowed_chats`. | | I asked the owner to approve this group. Until then I do not read it. | The owner must approve the group. | | This group is waiting for the owner's approval. | Same: approval is pending. | | In groups I can only read messages that mention me. | Mention the bot. Or turn on Discord's Message Content Intent, then turn the chat app off and on again (or enter its token again). | | You cannot run commands here. | The command is not allowed for you in this chat: you lack the `control` right, or the command does not work here (`bind` works only in groups). | | My answer to your message was lost. Send it again. | Delivery failed. Send the message again. | | Something went wrong before I could answer. Send your message again. | The Bot's turn failed. Send it again. | | I finished without an answer. | The Bot ended its turn without text. Ask again or check the session. | | (the rest of this answer is in the session) | The answer was longer than `max_parts` parts. | ### Messages sent while the chat app was down Messages people sent to the bot while the chat app was down may be lost. The chat app's `last_gap` says when that last happened: `from` and `to` are the start and end of the window. With `possible: true`, messages may have been lost, not certainly. No `last_gap` means no gap was recorded; it does not guarantee that no messages were missed. The TUI shows it in the chat app's details as "may have missed messages from … to …" when `possible` is true, and "missed messages from … to …" otherwise. Ask people who wrote in that window to send their message again. ## The bot does not answer at all 1. Check the state and follow the advice for it under [States](#states). `awaiting_owner` requires owner pairing for direct messages, but permitted group conversations can still work. 2. Check that the chat app admits you. When `dm_policy` (DMs) or `group_mode` (groups) is `open`, unpaired users can chat as guests, subject to chat restrictions and blocklists. Paired users still need the `chat` right. Otherwise, your user must be in the chat app's people (`principals`) with the `chat` right. `dm_policy: owner` admits only the owner in direct messages. 3. In a group: check that `group_mode` is not `off`, the group is not muted, and the group is `approved` unless `group_mode` is `open`. If `allowed_chats` is not empty, check that it includes the group; `allowlist` requires it. If `mention_only` is true, address the bot with a mention or a reply. On Telegram, if privacy mode stops the bot reading the messages you need, turn privacy off at @BotFather, then remove the bot from the group and add it again: Telegram applies the change only when the bot joins. Making the bot an admin of the group works too. 4. Send text. A file, image or voice message with no text does not reach the Bot. 5. Check that the Bot itself answers: send it a message in the TUI. **Most problems show their name in the state. The fix is usually one step away.**