Troubleshooting

Common issues and the quickest checks to run before opening a support ticket.

Agent Issues

Agent status is Error

Your agent crashed repeatedly in a short window.

Fix:

1. Open the agent and check Logs.
2. Look for invalid config, missing credentials, dependency errors, out-of-memory messages, or provider authentication errors.
3. Fix the root cause.
4. Click Restart.

Agent is stuck on Starting

1. Wait up to 60 seconds on cold start.
2. Check Logs for startup errors.
3. Stop and Start again if the previous container did not shut down cleanly.
4. If logs are empty and status does not change, contact support with the agent ID.

Agent auto-sleeps

Sleeping Free agents wake on the next message. Cron jobs and platform listeners require the container to be active at the time they run.

Agent works in dashboard chat but not Telegram/Discord/Slack

Dashboard chat can use a platform path even when the external connector is not active. Platform connectors require the container to be Active.

Fix:

1. Start the agent container.
2. Verify the integration token in the Integrations tab.
3. Restart after saving tokens or allowlists.
4. Check platform-side permissions, such as Discord Message Content Intent or Telegram group privacy mode.

Agent lost files or memory

Chat history is stored in Hatcher. Framework memory and workspace files live in the agent Docker volume.

• Restarting does not delete memory.
• Auto-sleep does not delete memory.
• Deleting the agent deletes the workspace volume.
• If files disappear without deletion, check Logs for workspace mount errors.

LLM And AI Credits

Hosted usage says insufficient AI Credits

Hosted UsePod/OpenRouter calls, hosted web search, research, extract, crawl, and embedding/tool calls can spend AI Credits.

Fix:

• Buy an AI Credit pack.
• Upgrade to a tier with a larger monthly grant.
• Switch the agent to BYOK so the provider bills your own account.

BYOK key not working

1. Test the key directly in the provider console.
2. Confirm the provider and model match the key.
3. Check provider billing and rate limits.
4. Restart the agent after saving model credentials.
5. Review Logs for 401, 403, 404, or provider-specific error messages.

Agent says it is using the wrong model

Model changes are saved in Hatcher config, but runtimes may need a restart to reload environment/config files. Restart the agent and re-check the dashboard model selector.

Responses are slow

Common causes:

• Large hosted or BYOK model selection
• Free tier CPU/RAM limits
• Agent waking from Free-tier sleep
• Tool-heavy messages with web search or file operations
• Provider-side latency

Integration Issues

Telegram bot not responding

1. Token format should look like 123456789:ABCdef....
2. Start or restart the agent after saving the token.
3. In groups, either mention the bot or disable BotFather privacy mode.
4. If group policy is allowlist, add allowed user IDs or switch the policy to open.
5. Confirm any group allowlist includes the group ID.

See Telegram integration.

Discord bot is offline or silent

1. Enable Message Content Intent in the Discord Developer Portal.
2. Reinvite the bot with send/read permissions.
3. Restart the agent after token changes.
4. Check the channel permissions for the bot role.

See Discord integration.

WhatsApp QR expires

QR codes expire quickly. Generate a new pairing QR, keep your phone ready, and scan from WhatsApp linked devices.

X/Twitter read operations fail

X Free API access is write-limited. Reading timelines, mentions, search, or replies requires an X developer plan with credits loaded in X’s own developer portal.

Billing Issues

Can’t create more agents

Your account is at its agent cap. Upgrade or buy stackable agent-slot add-ons:

• +1 Agent
• +3 Agents
• +5 Agents
• +10 Agents

Payment failed or did not activate

Hatcher currently supports card, SOL on Solana, USDC on Solana, and $HATCHER on Solana.

1. Check wallet balance and SOL for gas.
2. Confirm the transaction on Solscan.
3. Refresh the billing page after confirmation.
4. For card checkout, check for a Stripe receipt and wait for webhook settlement.
5. Contact support with the transaction signature or Stripe receipt ID if activation does not land.

Old credit endpoints return 410

Legacy cash-equivalent credits are retired. Plans and add-ons are paid with card or supported Solana rails. AI Credits are only for hosted usage, not plan checkout.

Framework-Specific Issues

Still Stuck?

• Email [email protected]
• Join Discord 
• Include the agent ID, timestamp, payment signature if relevant, and the most recent log snippet