---
title: Troubleshooting
description: "Common issues and how to fix them."
---

# Troubleshooting

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

<img src="https://indigo-decent-condor-546.mypinata.cloud/ipfs/bafybeibstpvk6pqo23ks3vork3yzr6ns5mdeltkv5snrkpgxn3j6pkgoau" alt="Agentbot troubleshooting" height="360" style={{borderRadius: '12px', width: '100%', objectFit: 'cover', marginBottom: '24px'}} />

## Installation Issues

<AccordionGroup>

<Accordion icon="bug" title="npm install fails with peer dependency errors">

```bash
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.

</Accordion>

<Accordion icon="bug" title="Prisma generate fails">

```bash
npx prisma generate
```

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

</Accordion>

<Accordion icon="bug" title="Port 3000 already in use">

```bash
lsof -i :3000
kill -9 <PID>
```

Or use a different port:

```bash
PORT=3001 npm run dev
```

</Accordion>

</AccordionGroup>

## Deployment Issues

<AccordionGroup>

<Accordion icon="bug" title="Vercel build fails with module not found">

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

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

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

</Accordion>

<Accordion icon="bug" title="Railway 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`)
- Missing environment variables causing startup crash

Check Railway logs for the actual error.

</Accordion>

<Accordion icon="bug" title="Environment variables not loading">

Agentbot reads env vars at startup. After changing them:

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

</Accordion>

</AccordionGroup>

## Agent Issues

<AccordionGroup>

<Accordion icon="bug" title="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

</Accordion>

<Accordion icon="bug" title="Agent running out of memory">

Each agent has a memory limit based on plan:

| Plan | Memory | CPU | Description |
|------|--------|-----|-------------|
| Solo | 2 GB | 1 vCPU | Trial / light workloads only |
| Collective | 4 GB | 2 vCPU | Recommended production floor |
| Label | 8 GB | 4 vCPU | Heavy production + browser/tool work |
| Network | 16 GB | 8 vCPU | High-throughput production |

If you're hitting memory limits, check for memory leaks in custom skills or upgrade your plan. The Solo tier (1 vCPU / 2 GB) is the trial/light-use floor — for production workloads, we recommend at least Collective (2 vCPU / 4 GB).

</Accordion>

<Accordion icon="bug" title="Skills not loading">

```bash
# Open the user-facing skills surface
GET /dashboard/skills

# Marketplace/API install flow
POST /api/skills
{ "skill": "weather" }
```

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

</Accordion>

<Accordion icon="bug" title="Agent offline when installing skills">

If you see **"Agent offline. Install your agent first, then retry installing skills."** in the dashboard, the skill was saved to your account but the agent's gateway is not reachable.

This happens when the API returns `"deployed": false` with a `deployWarning` field. To resolve:

1. Verify your agent is running: `GET /api/agents/{id}`
2. Start or restart the agent from the dashboard
3. The skill will sync automatically once the agent comes back online
4. You can also trigger a manual sync using `POST /api/agents/{id}/sync`

See the [Skills API reference](/api-reference/skills#install-skill) for full response details.

</Accordion>

</AccordionGroup>

## Billing Issues

<AccordionGroup>

<Accordion icon="bug" title="Stripe checkout returns 410 Gone">

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

```http
GET /api/stripe/checkout?plan=solo
```

</Accordion>

<Accordion icon="bug" title="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

</Accordion>

</AccordionGroup>

## Getting Help

- **Discord:** [discord.gg/vTPG4vdV6D](https://discord.gg/vTPG4vdV6D) — Community support
- **GitHub Issues:** [Eskyee/agentbot-opensource](https://github.com/Eskyee/agentbot-opensource/issues) — Bug reports
- **GitHub Discussions:** [Eskyee/agentbot-opensource/discussions](https://github.com/Eskyee/agentbot-opensource/discussions) — Questions and ideas
