Troubleshooting

Common issues and how to fix them.

Troubleshooting

Common issues when building, deploying, and running Agentbot agents.

Installation Issues

npm install fails with peer dependency errors

npm install --legacy-peer-deps

Agentbot uses React 19 which some packages haven’t updated for yet. The --legacy-peer-deps flag resolves most conflicts.

Prisma generate fails

npx prisma generate

Prisma client must be generated before build. If you see @prisma/client did not initialize, run the generate command manually.

Port 3000 already in use

lsof -i :3000
kill -9 <PID>

Or use a different port:

PORT=3001 npm run dev

Deployment Issues

Vercel build fails with module not found

Check that all imports use the @/ alias correctly. The @/ prefix maps to the web/ directory. Common mistake:

// ❌ Wrong
import { auth } from '../../../lib/auth'

// ✅ Right
import { auth } from '@/app/lib/auth'

Render deploy fails — health check timeout

The health check at /health must respond within 60 seconds. Common causes:

• Database connection string is wrong (check DATABASE_URL)
• Redis isn’t reachable (check REDIS_URL)
• Missing environment variables causing startup crash

Check Render logs for the actual error.

Environment variables not loading

Agentbot reads env vars at startup. After changing them:

• Vercel: Redeploy from dashboard or vercel --prod
• Render: Service auto-restarts on env change
• Local: Restart the dev server (npm run dev)

Agent Issues

Agent not responding to messages

1. Check agent status: GET /api/agents/{id}
2. Verify the channel token (Telegram/Discord/WhatsApp) is valid
3. Check the agent container logs
4. Ensure the AI provider API key is set and has credits

Agent running out of memory

Each agent has a memory limit based on plan:

Plan	Memory
Solo	2GB
Collective	4GB
Label	8GB
Network	16GB

If you’re hitting limits, check for memory leaks in custom skills or upgrade your plan.

Skills not loading

# List installed skills
GET /api/agents/{id}/skills

# Reinstall a skill
POST /api/agents/{id}/skills
{ "skillId": "weather" }

Skills are loaded at agent startup. If a skill fails to load, the agent will start without it and log the error.

Billing Issues

Stripe checkout returns 410 Gone

The legacy /api/checkout endpoint is deprecated. Use:

GET /api/stripe/checkout?plan=solo

BYOK not working

1. Verify your API key is valid (test it with curl)
2. Check the provider name matches exactly: openrouter, anthropic, openai, google, groq
3. Ensure the key has credits/quota remaining
4. Disable and re-enable BYOK from the billing dashboard

Getting Help

• Discord: discord.gg/eskyee — Community support
• GitHub Issues: Eskyee/agentbot-opensource — Bug reports
• GitHub Discussions: Eskyee/agentbot-opensource/discussions — Questions and ideas