Troubleshooting Common Issues
Table of Contents
This guide covers the most common issues you'll encounter when running agents on Agento and how to resolve them quickly.
Agent Won't Start
If your agent stays in a "stopped" or "error" state after clicking Start:
Check your credentials. The most common cause is missing or invalid API credentials. Go to Settings and verify your AI provider is connected. For API-key providers (Anthropic, Gemini), make sure the full key was pasted without extra spaces. For OpenAI OAuth, try disconnecting and reconnecting.
Check the agent logs. Open the Logs tab on your agent page. Look for error messages near the top — they usually point directly at the problem. See the Reading Your Agent Logs guide for details.
Restart the agent. Sometimes a simple restart resolves transient issues. Click Stop, wait a few seconds, then click Start again.
Agent Responds Slowly
Slow responses are usually caused by the AI model, not Agento itself.
Switch to a faster model. Claude Haiku and Gemini Flash respond in 1-2 seconds. Larger models like Claude Opus or GPT-5.2 can take 5-15 seconds for complex prompts.
Check provider status. AI providers occasionally experience high load. Check their status pages:
Simplify your system prompt. Very long system prompts increase latency because the model processes them on every message. Keep your prompt focused and under 1,000 words when possible.
Agent Gives Wrong or Unexpected Answers
Refine the system prompt. The most impactful fix is usually improving your instructions. Be specific about what the agent should and shouldn't do. See the Personalizing Your Agent guide.
Start a new session. Conversation context accumulates over a long session. If the agent seems "confused," start a fresh session to clear the history.
Try a different model. Different models have different strengths. Claude Opus excels at nuanced reasoning, Gemini Pro handles structured data well, and GPT-5.2 is strong at creative tasks.
Credential Errors
"Invalid API key"
- Anthropic: Keys start with
sk-ant-. Make sure you copied the complete key. - Gemini: Keys start with
AI. Verify the key in Google AI Studio. - OpenAI: Uses OAuth, not API keys. Disconnect and reconnect through the Settings page.
"Rate limit exceeded"
Your AI provider account has hit its usage limit. Options:
- Wait — rate limits reset automatically (usually within minutes)
- Switch models — smaller models have higher rate limits
- Upgrade your provider plan — increase your API tier for higher limits
"Insufficient funds" / "Billing error"
Your AI provider account needs a payment method or additional credits. Log in to your provider's dashboard and check billing.
Telegram Bot Not Responding
Verify agent is running. The agent must be in a "running" state to process Telegram messages.
Check the Channels tab. Make sure Telegram shows "Connected" with a green indicator. If it shows disconnected, re-enter the BotFather token.
Send /start in Telegram. New conversations with a bot require sending /start first.
Check the token. If you regenerated the BotFather token, the old one is invalidated. Update it in Agento's Channels tab.
Web Chat Issues
"Agent offline" message: The agent isn't running. Start it from the dashboard.
Chat won't load: Try a hard refresh (Ctrl+Shift+R / Cmd+Shift+R). If the problem persists, check your internet connection.
Messages disappear after refresh: This shouldn't happen — sessions are stored server-side. If you're seeing this, try logging out and back in.
Container Issues (Root Access)
"Permission denied" errors: If you need the agent to install packages or write to system directories, enable Sudo Access in Settings > Advanced. Restart the agent after enabling. See the Enabling Root Access guide.
Installed packages disappear: Packages persist within a container's lifetime but may be lost on certain restarts (e.g., after an image upgrade). For packages your agent needs regularly, include the installation step in your system prompt.
Still Stuck?
If none of the above resolves your issue:
- Copy your agent logs — they contain the most diagnostic information (see Reading Your Agent Logs)
- Contact support — email [email protected] with your agent ID and logs
- Check our blog — we publish guides on common patterns and fixes at agento.host/blog