Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Troubleshooting

Start here: bento doctor

bento doctor

Checks the daemon process, database connection, cloudflared / tailscale availability, and webhook reachability. Most setup problems show up here with a plain-text description.

Daemon won't start

Symptom: bento daemon start exits immediately or bento status shows the daemon as unreachable.

  1. Check the daemon log: 
    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: 
    bento doctor
# → local: reachable, tunnel: reachable
  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 restart.
  4. Confirm the webhook secret in GitHub matches webhooks.secret in daemon.yaml. A mismatch returns 401 and silently drops the event.
  5. Check daemon logs for signature verification errors: 
    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: 
    bento trace <event-id>
  2. Check queue depth — a backlog may delay the run: 
    bento queue status
  3. Check defaults.limits.max_concurrent in daemon.yaml. If all slots are taken, new jobs queue behind the running ones.

Agent run failed or timed out

Symptom: The run appears in bento status but shows failed or timeout.

  1. Read the agent's stdout: 
    bento logs <invocation-id>
  2. Increase guardrails.timeout in the pipeline file if the task is genuinely long-running.
  3. Check for sandbox issues — if the agent can't clone the repo or reach the network, it fails early: 
    bento probe <invocation-id>
  4. Check queue.circuit_breaker.failure_threshold — repeated failures open the circuit and stop queuing jobs for that pipeline until the daemon restarts.

Authentication failures

Symptom: 401 Unauthorized from the daemon or MCP client can't connect.

  1. List issued tokens: 
    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: 
    bento token issue --email you@example.com
    See Authentication for client setup.

Tunnel not reachable

Symptom: bento 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 start. Run bento status again after a few seconds.
  • Check daemon logs for cloudflared errors: 
    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.

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 Inspecting Runs.