Skip to content
agentFast
Reference

Troubleshooting

The things that break in the first hour, and what to do.

Roughly in the order people hit them.

Setup

ModuleNotFoundError: No module named 'langgraph'

The SDK extras aren't installed. Each adapter is an optional dependency so a LangGraph project doesn't carry CrewAI's tree:

pip install -e ".[langgraph,dev]"      # or crewai, claude-agent-sdk, openai-agents

connection refused on port 5432

Postgres isn't running, or AGENTFAST_DATABASE_URL points somewhere else. Check what you've got:

echo $AGENTFAST_DATABASE_URL
docker compose ps

To get moving without a database — demos and UI work only — agentfast serve --in-memory works, but a restart loses every run.

relation "runs" does not exist

The database exists but has no schema:

alembic upgrade head

If the tables are already there from an older install, tell Alembic where it's starting from instead: alembic stamp 0001_baseline.

The pgvector image fails on Apple Silicon

Pull the arm64 image. An amd64 pull appears to work and then corrupts under load, which is a miserable way to spend an afternoon.

Running an agent

The agent never calls my tool

Almost always the description, not the code. The model reads it to decide when the tool is relevant.

# Won't get called
@tool("Gets subscription data.")

# Will
@tool("Look up a customer's current subscription: plan, seats, renewal date "
      "and outstanding balance. Use this before answering any billing question.")

Check it's actually registered while you're there:

curl localhost:8321/api/health
agentfast mcp list        # if it came from an MCP server

The agent never pauses for approval

Three things to check, in order:

  1. Is the tool marked high-risk in agentfast.yaml? risk: low never pauses.
  2. Does the name match exactly? tool_overrides keys are tool names — a typo silently does nothing.
  3. Is it hitl_mode: defer? Defer queues the call and lets the run continue by design. If you wanted it to stop, you want suspend.

A run is stuck on paused forever

That's a run waiting for a human, working exactly as intended. Someone has to decide:

agentfast approvals list
agentfast approvals approve appr_… --by you@company.com

If this keeps happening, nobody's watching the queue — see the note at the end of Deploy.

budget exhausted: iteration limit reached (50)

The agent used its whole allowance. Either the task genuinely needs more, or it's looping. Look at the step tree first — a loop usually shows as the same tool called repeatedly with near-identical input, which is a prompt problem, not a budget one.

budget:
  max_iterations: 100

Costs show as $0.00

The model isn't in your pricing table. Add it:

observability:
  pricing:
    your-model-id:
      input_per_1m: 3.00
      output_per_1m: 15.00
      cache_read_per_1m: 0.30

The UIs

The playground can't reach the API

Nearly always CORS. The API only allows the origins you list:

cors_origins: ["http://localhost:3400", "http://localhost:3401"]

A front end on any other port or domain — including a Vercel preview URL — has to be added. The browser console will say so explicitly.

401 missing or invalid bearer token

api_auth_token is set on the API but the client isn't sending it. Either give the client the token or unset it locally.

The stream just hangs

  • Behind nginx or a managed proxy? Response buffering turns a live stream into one delivery at the end. agentFast sends X-Accel-Buffering: no; some proxies need it configured server-side too.
  • Nothing arriving at all? Check the run actually started — GET /api/runs — before suspecting the stream.
  • Long gaps with no events are normal during a slow tool call. The stream sends a heartbeat comment every 15 seconds to keep the connection alive.

Reconnecting started a second run

You reconnected by re-sending POST /api/chat/stream. That starts a new run — tools and all. Reconnect against the existing run instead:

GET /api/runs/{run_id}/stream

See Streaming. The vendored client does this for you.

Re-attaching finds nothing, but the run is going

You're running multiple workers and the request landed on one that doesn't own the run. The event bus is in-process today. The replay still comes from Postgres, and polling GET /api/runs/{id} works across workers.

Evals

agentfast eval fails but the answers look fine

Read which metric failed. grounding failing with good-looking answers usually means the agent answered from the model's own knowledge rather than your knowledge base — correct today, wrong the moment your policy changes. That's the eval doing its job.

The judge is failing everything

It fails closed on purpose: an errored, timed-out or unparseable judge marks the case failed rather than passing it. Check the judge model is configured and its API key is present. A broken judge must never produce a green build.

Still stuck

# What the API thinks it's running
curl localhost:8321/api/health

# The full step tree for a run — usually answers it
curl localhost:8321/api/runs/run_abc | python -m json.tool

The step tree is the first place to look for almost everything. It records what the agent saw, what it did, what each step cost, and where it stopped.

Otherwise: open an issue with the run id and the relevant part of the step tree.