Troubleshooting

costaff start aborts with config errors

That's the preflight check working as intended — it found something fatal in .env (missing API key, missing DB URI) and printed the exact fix. Most issues resolve with costaff onboard, which keeps your existing settings as defaults. If you really need to start anyway: costaff start --no-preflight.

The bot replies "your account has not been approved"

Not a bug — the approval gate (on by default). The first message from any chat account creates a pending identity. Fix: costaff dashboard → Users → approve the new row → message again.

The assistant mentions "quota", "429", or "RESOURCE_EXHAUSTED"

You hit the Gemini free tier's per-minute or per-day rate limit. Nothing is broken and nothing is being charged — wait a minute (or until the daily reset) and try again. If you hit it constantly, switch to a paid Gemini key or another provider via costaff onboard.

Docker permission denied (Ubuntu)

Symptom: docker: Got permission denied while trying to connect to the Docker daemon socket.

Cause: your shell hasn't picked up the docker group yet.

Fix: log out and back in, or run newgrp docker in a fresh shell.

Port 18080 already in use

Another service is bound to the Manager's port. Either stop the other service, or override the port in ~/.costaff/costaff/.env:

COSTAFF_AGENT_PORT=18180

Then costaff restart. Channel and agent ports are auto-assigned from free slots (18090–18099 / 18100–18199), so they dodge collisions on their own.

Agent shows unhealthy in costaff agent list

Check the container's logs:

docker logs costaff-agent-<name> --tail 50

Most common causes:

• Missing API key — set the required key in ~/.costaff/costaff-agent/<name>/.env, then costaff agent rebuild <name>.
• Bad model name — try costaff agent model <name> to inspect, set a known-good model, rebuild.
• Port collision — the agent's auto-assigned port is taken; remove and re-add.

Manager not picking up a new agent

Right after costaff agent add, the Manager is restarted to refresh its sub-agent list. If it didn't take, force it:

costaff agent restart costaff
# or rebuild the manager if you changed env vars
docker compose -f ~/.costaff/costaff/docker-compose.yaml \
  up -d --build --force-recreate costaff-agent-costaff

Wipe and start over

costaff stop
docker compose -f ~/.costaff/costaff/docker-compose.yaml down -v
rm -rf ~/.costaff/workspace/*
costaff start

This drops the Postgres volume and clears all agent workspaces. Your .env, registered agents, and channel configs stay in place.

Still stuck

Open an issue on the main repo with costaff doctor output attached, or email simonliuyuwei@gmail.com.