Troubleshooting chat apps
Section titled “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
Section titled “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. | 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. |
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
Section titled “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). 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
Section titled “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
Section titled “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 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. |
The Bot is gone from the list
Section titled “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.
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.
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.
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.
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
Section titled “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 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
Section titled “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
Section titled “The bot does not answer at all”- Check the state and follow the advice for it under States.
awaiting_ownerrequires owner pairing for direct messages, but permitted group conversations can still work. - Check that the chat app admits you. When
dm_policy(DMs) orgroup_mode(groups) isopen, unpaired users can chat as guests, subject to chat restrictions and blocklists. Paired users still need thechatright. Otherwise, your user must be in the chat app’s people (principals) with thechatright.dm_policy: owneradmits only the owner in direct messages. - In a group: check that
group_modeis notoff, the group is not muted, and the group isapprovedunlessgroup_modeisopen. Ifallowed_chatsis not empty, check that it includes the group;allowlistrequires it. Ifmention_onlyis 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. - Send text. A file, image or voice message with no text does not reach the Bot.
- 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.