Troubleshooting

Work top to bottom. Most first-run failures are “stack not up”, “wrong Node”, or “API cannot see the CLI / Ollama”.

1. Is the API up?

curl -s http://localhost:8000/healthz
curl -s http://localhost:8000/version
curl -sS -o /tmp/ready.json -w "%{http_code}\n" http://localhost:8000/readyz

Result	Meaning
`healthz` fails	uvicorn is not running, or `PORTO_PORT` is not 8000.
`readyz` is 503	Read the `checks` in the body. Almost always Supabase is down.
`version.sha` is stale	You pulled git and did not restart the API.

Start Supabase from frontend/: supabase start. Then restart uvicorn.

2. Frontend cannot connect

NEXT_PUBLIC_PORTO_WS_URL must match the API (ws://localhost:8000/ws by default).
Browser console will show a WebSocket error if the API is down.
A production next start build inlines env at build time. After changing .env.local, re-run npm run dev (or rebuild).

3. CLI seat will not spawn

whoami
which grok claude codex vibe

The API must run as that user, with that PATH. Start uvicorn from the same terminal, not from a GUI wrapper with a thin PATH. See CLI harnesses.

4. Local model never answers

curl -s http://127.0.0.1:11434/api/tags
curl -s http://127.0.0.1:11434/v1/models

No listener → start Ollama / vLLM / LM Studio.
Listener on the laptop, API in Docker → 127.0.0.1 inside the container is not your laptop. Use a LAN / Tailscale URL, or run the API on the host.
First token > 30s on a cold Qwen is normal. porto waits 300s for Ollama and Local / network.

5. Key rejected on Save

porto probes the provider before persist. A 401 from the vendor is a bad key. A timeout is network / wrong base URL. Blank key on edit keeps the stored secret. Blank key on Ollama / Local is allowed.

6. `setup.sh` stops on Docker

Docker is installed but the daemon isn't running

Start Docker Desktop. Re-run ./setup.sh. The script is idempotent.

7. Node / Python mismatch

./scripts/check-versions.sh

Node 20 or 22 only. Python 3.11. nvm use in frontend/ (reads .nvmrc). pyenv local in backend/ (reads .python-version).

8. Ports already bound

Port	Owner
3000	Frontend
8000	Backend
54321–54324	Local Supabase

lsof -nP -iTCP:3000 -sTCP:LISTEN
lsof -nP -iTCP:8000 -sTCP:LISTEN

9. Encryption key changed

If you rotate PORTO_ENCRYPTION_KEY, old credential rows will not decrypt. Re-save each provider in Settings, or restore the previous key.

Still stuck

cd frontend && supabase status
curl -s http://localhost:8000/readyz
Backend terminal — look for structured logs (adapter_invoked, provider_error), not a Python traceback you have to guess.

Do not paste service-role keys or API keys into a chat when you ask for help. Redact them.

​1. Is the API up?

​2. Frontend cannot connect

​3. CLI seat will not spawn

​4. Local model never answers

​5. Key rejected on Save

​6. setup.sh stops on Docker

​7. Node / Python mismatch

​8. Ports already bound

​9. Encryption key changed

​Still stuck