> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentbot.raveculture.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> 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 theme={"dark"}
    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 theme={"dark"}
    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 theme={"dark"}
    lsof -i :3000
    kill -9 <PID>
    ```

    Or use a different port:

    ```bash theme={"dark"}
    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 theme={"dark"}
    // ❌ 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 theme={"dark"}
    # 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 theme={"dark"}
    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