🔧

When Things Go Wrong

Common issues, fixes, and how to get help when you need it

12 min read
Advanced

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:

    1. Check agent status in your dashboard

    2. Restart your agent (Settings → Restart)

    3. Wait 2-3 minutes for it to come back online

    4. 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:

    1. Bot Token: Make sure it's correct and starts with a number

    2. Chat ID: Verify you're using the right Chat ID

    3. 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:

    - Anthropic: status.anthropic.com

    - GitHub: githubstatus.com

    - Vercel: vercel-status.com

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

    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

    1. Immediately revoke all API keys in the original services

    2. Stop your agent from the dashboard

    3. Contact our support with details

    4. Generate new API keys before restarting

    5. Review recent activity for unauthorized actions

    If You Lose Access to Your Account

    1. Use account recovery on the sign-in page

    2. Check your email for recovery instructions

    3. Contact support if recovery doesn't work

    4. 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.*

    Was this helpful?

    Related Guides

    🔑Configuration

    API Keys & Security

    How we handle API keys, security best practices, and where to get them

    12 min
    💬Configuration

    Connecting Telegram

    Step-by-step guide to set up Telegram bot integration

    8 min