Home/Guides/When Things Go Wrong

When Things Go Wrong

Advanced12 min read

When Things Go Wrong

Don't panic! AI agents are complex systems, and sometimes things get wonky. Here's how to fix the most common issues you might run into.

Quick Diagnostics

Before diving into specific problems, let's check the basics:

Agent Status Check

Go to your agent dashboard
Look for the status indicator (should be green/online)
Check "Last Activity" timestamp
Review recent logs if available

API Key Health

Go to Settings → API Keys
Check for any red warning icons
Verify keys haven't expired
Test with a simple command

Common Issues & Fixes

🤖 Agent Not Responding

Symptoms: Your agent doesn't reply to messages or seems offline.

Quick fixes:

Check agent status in your dashboard
Restart your agent (Settings → Restart)
Wait 2-3 minutes for it to come back online
Try a simple test like "Hello" or "What time is it?"

If still not working:

Check if your Anthropic API key is valid
Look at the agent logs for error messages
Verify your plan hasn't expired
Make sure the agent wasn't accidentally stopped

💬 Telegram Bot Not Working

Symptoms: Bot doesn't respond on Telegram, or you get "bot not found" errors.

Check these first:

Bot Token: Make sure it's correct and starts with a number
Chat ID: Verify you're using the right Chat ID
First message: Did you send at least one message to the bot first?

Step-by-step fix:

Go to your bot on Telegram
Send "/start" to wake it up
Wait 30 seconds
Try sending "Hello"
If nothing, check your agent dashboard for Telegram settings

Advanced troubleshooting:

Test your bot token with Telegram's API: https://api.telegram.org/botYOUR_TOKEN/getMe
Make sure you haven't blocked the bot
Check if the bot username is correct

🔑 API Key Problems

Symptoms: "Invalid API key", "Authentication failed", or plugins not working.

For Anthropic keys:

Must start with sk-ant-
Check at console.anthropic.com
Make sure you have sufficient credits
Try generating a fresh key

For GitHub tokens:

Must start with ghp_ or github_pat_
Check expiration date
Verify permissions include repo and workflow
Test with: curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user

For other services:

Double-check you copied the full key
Verify the key has the right permissions
Check if the service requires IP whitelisting
Look for usage limits or billing issues

🧩 Plugins Not Working

Symptoms: Agent ignores plugin commands or says it can't do something.

Check plugin status:

Go to Settings → Plugins
Make sure the plugin is "Active"
Verify required API keys are configured
Try reinstalling the plugin

Common plugin issues:

GitHub Plugin:

Make sure repo exists and you have access
Check if it's a private repo (needs appropriate permissions)
Verify branch names are correct

Vercel Plugin:

Confirm project exists in your Vercel dashboard
Check if project is linked to the right Git repo
Make sure you have deployment permissions

EVM Wallet Plugin:

Verify wallet has sufficient ETH for gas
Check if the network is congested (high gas)
Make sure private key format is correct

🚀 Deployment Failures

Symptoms: Agent creation fails, or agent stops working after initial setup.

During agent creation:

Check if the region you selected is available
Verify your payment method is valid
Make sure you have sufficient credits/quota
Wait longer — initial deployment can take 5-10 minutes

After deployment:

Check server logs in your dashboard
Verify all API keys are working
Look for memory/CPU usage spikes
Try restarting the agent

📱 Web Dashboard Issues

Symptoms: Dashboard won't load, or you can't access agent settings.

Browser issues:

Try a different browser
Clear cache and cookies
Disable browser extensions temporarily
Check if JavaScript is enabled

Account issues:

Make sure you're signed in
Verify your subscription is active
Check if your account has the right permissions
Try signing out and back in

💸 Billing & Plan Issues

Symptoms: Agent stopped working, can't access features, or getting upgrade prompts.

Check your plan:

Go to Account → Billing
Verify subscription status
Check usage limits (if on Light plan)
Review payment method status

Common billing fixes:

Update expired payment method
Check if you hit plugin limits (Light plan)
Verify subscription auto-renewal settings
Contact support for billing disputes

Performance Issues

Agent Responding Slowly

Possible causes:

High Anthropic API latency
Complex plugins taking time to process
Server overload during peak hours
Large file operations

What you can do:

Try simpler requests first
Check Anthropic status page
Avoid large file operations during peak hours
Break complex requests into smaller parts

Commands Timing Out

If commands take too long:

Check if the external service (GitHub, Vercel) is having issues
Try the same request with fewer parameters
Make sure you're not hitting rate limits
Consider if the operation is inherently slow (large deployments)

Getting Help

Self-Service Options

Agent Logs: Check your dashboard for error messages and stack traces.

Service Status Pages:

Test API Keys Manually: Use curl or API testing tools to verify your keys work outside of Claws.

Community Help

Discord Community: Join our Discord for quick help from other users and the team.

GitHub Discussions: Check our GitHub repo for known issues and solutions.

Reddit/Forums: Search for others who might have had similar issues.

Contacting Support

When to contact us:

Agent has been down for >30 minutes
Billing/payment issues
Data loss or security concerns
Bug in our platform (not external services)

What to include:

Your agent name/ID
What you were trying to do
Error messages (screenshots help)
When the issue started
What you've already tried

Response times:

Urgent issues (agent completely down): 2-4 hours
Billing issues: Within 24 hours
General questions: 1-2 business days

Preventive Measures

Regular Maintenance

Monthly:

Review and rotate API keys
Check usage against your plan limits
Update expired tokens before they break
Clean up old/unused plugins

Weekly:

Test critical commands to make sure they work
Check agent logs for warnings
Verify backups if you have custom files

Good Practices

API Keys:

Set expiration reminders
Use descriptive names for keys
Monitor usage in service dashboards
Keep keys secure (don't share them)

Agent Usage:

Start with simple commands when testing
Don't overload with too many simultaneous requests
Keep custom personality files backed up
Monitor your Anthropic usage/costs

Emergency Procedures

If Your Agent Gets Hacked

Immediately revoke all API keys in the original services
Stop your agent from the dashboard
Contact our support with details
Generate new API keys before restarting
Review recent activity for unauthorized actions

If You Lose Access to Your Account

Use account recovery on the sign-in page
Check your email for recovery instructions
Contact support if recovery doesn't work
Provide proof of ownership (billing info, agent details)

Data Recovery

If you lose important data:

Check if you have local backups
Look for data in the original services (GitHub repos, etc.)
Contact support — we might have recent backups
Consider this a good reminder to back up important custom files

What's Next?

Once you've got things working again:

Set up monitoring for your most critical API keys
Create backups of any custom personality or configuration files
Join our community to stay updated on known issues
Consider upgrading your plan if you hit limitations

Remember: every problem is solvable, and we're here to help. Don't let technical issues stop you from building awesome things with your AI agent! 🛠️✨

Still stuck? Reach out to our community or support team. We've probably seen your issue before and can help you fix it quickly.