# Troubleshooting ## Start here: `bento doctor` ```bash bento doctor ``` Checks the daemon process, database connection, `cloudflared` / `tailscale` availability, and webhook reachability. Exits with a plain-text description of any failures found. *** ## Daemon won't start **Symptom:** `bento daemon start` exits immediately or `bento daemon status` shows the daemon as unreachable. 1. Check the daemon log: ```bash bento daemon logs ``` 2. Common causes: * **Port 7890 already in use** — `lsof -i :7890` to find the occupant * **Database unreachable** — confirm Postgres is running: `docker compose ps` * **Missing `GITHUB_WEBHOOK_SECRET`** — the variable must be set in your shell or `.env` file before `bento daemon start` *** ## Webhooks not firing **Symptom:** You open a PR and the daemon receives nothing. 1. Confirm the daemon is reachable from the internet: ```bash bento doctor ``` 2. Check the GitHub webhook delivery log (repo **Settings → Webhooks → Recent Deliveries**). Look for HTTP errors or timeouts. 3. If you're using a Cloudflare Quick Tunnel, the URL rotates on restart — re-register it with GitHub after every `bento daemon restart`. 4. Confirm the webhook secret in GitHub matches `webhooks.secret` in `daemon.yaml`. A mismatch returns `401`; GitHub records the failure in the delivery log. 5. Check daemon logs for signature verification errors: ```bash bento daemon logs -f ``` *** ## Agent run not appearing **Symptom:** A webhook was delivered (GitHub shows `200`) but no agent run shows up. 1. Check the pipeline trigger matches the event type. `pull_request.opened` and `pull_request.synchronize` are the most common: ```bash bento trace ``` 2. Check queue depth — a backlog may delay the run: ```bash bento queue status ``` 3. Check `queue.concurrency` in `daemon.yaml` (default 2). If all slots are taken, new jobs queue behind the running ones. *** ## Agent run failed or timed out **Symptom:** The run appears in `bento daemon status` but shows `failed` or `timeout`. 1. Read the agent's stdout: ```bash bento daemon logs ``` 2. Increase `guardrails.timeout` in the pipeline file. 3. Check for sandbox issues — if the agent can't clone the repo or reach the network, it fails early: ```bash bento probe ``` 4. Check `queue.circuit_breaker.failure_threshold` — repeated failures open the circuit and pause queuing for that pipeline. *** ## Authentication failures **Symptom:** `401 Unauthorized` from the daemon or MCP client can't connect. 1. List issued tokens: ```bash bento token list ``` 2. Verify the token your client is using matches one of the listed IDs. 3. Confirm the token's `scopes` permit the operation (e.g. `pipelines:*` for pipeline invocations). 4. Re-issue a token if needed: ```bash bento token issue --email you@example.com ``` See [Authentication](/authentication) for client setup. *** ## Tunnel not reachable **Symptom:** `bento daemon status` shows `tunnel : pending` or `tunnel : error`. **Cloudflare Quick Tunnel:** * Confirm `cloudflared` is on PATH: `which cloudflared` * The tunnel takes up to 5s to establish after `bento daemon start`. Run `bento daemon status` again after a few seconds. * Check daemon logs for `cloudflared` errors: ```bash bento daemon logs | grep tunnel ``` **Tailscale Funnel:** * Confirm the host is enrolled in your tailnet: `tailscale status` * Confirm HTTPS certificates are enabled in the Tailscale admin console (**DNS → HTTPS Certificates**) * Confirm Funnel is enabled (**Access Controls → Funnel**) * Run `tailscale funnel status` to verify the funnel is active *** ## Database issues **Symptom:** `database unreachable` in `bento doctor`. ```bash docker compose ps # is the container running? docker compose up -d # restart if stopped ``` The canonical Compose file sets up Postgres at `postgresql://bento:bento@localhost:8421/bento`. Confirm this matches `database.url` in `daemon.yaml`. *** ## Inspecting a specific run For deep inspection of a single invocation — agent stdout, prompt, context, and timing — see [Traces](/pipelines/traces).