Troubleshooting

Common issues and their solutions.

Bot Not Responding

Check Integration Status

1. Go to Bots → select your bot → Integrations
2. Verify the integration is enabled (toggle is on)
3. Check for any error messages

Verify Credentials

• Telegram: Ensure the bot token is valid. Test with @BotFather → /mybots
• Email: Verify Mailgun API key and domain configuration

Check Channel Authorization

1. Go to Channels → Authorized Channels
2. Verify the chat/channel ID is in the authorized list
3. If not listed, add it with the correct tenant

Verify API Keys

1. Go to Settings → API Keys
2. Check that a key exists for the bot's LLM provider
3. Verify the key status is Active

Slow Responses

Context Window Size

Large context windows increase response time. Try reducing the context window in bot settings.

Model Selection

Faster models:

• gpt-4o-mini (OpenAI)
• claude-3-haiku (Anthropic)
• gemini-flash (Google)

Orchestration Overhead

Multi-step orchestration adds latency. If speed is critical, consider:

• Reducing max orchestration steps
• Using direct agent routing instead of orchestration

Error Messages

Error	Cause	Fix
"App user not found"	User not synced from Clerk	Ensure Clerk webhooks are configured
"No API key available"	Missing provider key	Add a key in Settings → API Keys
"Chat not authorized"	Chat ID not in whitelist	Add chat to Authorized Channels
"Rate limited"	Too many requests	Wait and retry; consider upgrading

Getting Help

If you're still stuck:

1. Check the FAQ
2. Review the API Reference for detailed error codes
3. Contact support at mesa.chat