Troubleshooting

Work top to bottom. Most first-run failures are “stack not up”, “wrong Node”, or “API cannot see the CLI / Ollama”. Using the Mac app? Start with Desktop app (macOS). The numbered sections are for a from-source install.

Desktop app (macOS)

The app starts its own database, server and web app, and its start screen tells you which step it is on.

Start screen says	Meaning	What to do
“Setting up your local database…”	First launch is creating Porto’s database.	Wait. It usually takes about a minute.
“This is taking longer than usual”	A step is slow but Porto is still trying.	Leave the window open. If it ends in “Porto couldn’t start”, read the matching row below.
“Porto couldn’t start. Your local database didn’t start.”	Postgres or its setup failed.	Click Show logs. Read `porto-bundled-db.log` and `postgres.log`.
“Porto couldn’t start. Porto’s server stopped while starting.”	The API process exited.	Read `porto-bundled-api.err.log`.
“Porto couldn’t start. Porto’s interface stopped while starting.”	The web server exited.	Read `porto-bundled-web.err.log`.
“Porto couldn’t start. Porto took too long to start.”	Nothing failed outright, but the app gave up waiting.	Click Try again. If it repeats, read the API log.
“Porto is stopped”	You used Stack → Stop Porto.	Click Start Porto.

Try again restarts only the parts that are not running. You don’t need to quit the app first.

Log files

Show logs opens Finder at the API error log. The other logs sit next to it, except Postgres.

File	What it records
`/tmp/porto-bundled-api.err.log`	API errors, including a crash while starting
`/tmp/porto-bundled-api.log`	API output
`/tmp/porto-bundled-web.err.log`, `/tmp/porto-bundled-web.log`	Web app server
`/tmp/porto-bundled-db.log`	First-run settings file and database setup, including migrations
`~/Library/Application Support/Porto/logs/postgres.log`	Postgres itself

Each launch keeps the previous launch’s file with .1 added (for example porto-bundled-api.err.log.1). If the first launch failed and you opened the app again, the first launch’s log is the .1 file. macOS can clear /tmp when the Mac restarts, so copy the logs first if you need them. When you ask for help, attach these files. Read them first and remove anything private.

Ports

The app uses ports 3000 (web app) and 8000 (API) and moves to the next free port when another app already holds one. Its database always uses 54321, 54322 and 54329. If the database step fails, check what holds those ports:

lsof -nP -iTCP:54321 -sTCP:LISTEN
lsof -nP -iTCP:54322 -sTCP:LISTEN
lsof -nP -iTCP:54329 -sTCP:LISTEN

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. Seat Computer is off

curl -sS http://localhost:8000/computerz

`reason`	Fix
`flag_off`	Set `PORTO_COMPUTER=1` in `backend/.env`. Restart API and runner.
`docker_not_installed`	Install Docker Desktop. API PATH must include `docker` (`/usr/local/bin` on many Macs).
`docker_not_running`	Start Docker Desktop. Chat still works.
`image_missing`	Build `porto/computer:v1` on this host, then restart.
`api_in_container`	Run the native API on the laptop so it can talk to host Docker.
`vps_not_configured`	Host is VPS. Set `PORTO_COMPUTER_DOCKER_HOST` (`ssh://user@host` or `tcp://host:2376`), or unset `PORTO_COMPUTER_HOST`.
`vps_not_reachable`	VPS engine down or SSH/TCP failed. `DOCKER_HOST=… docker info`. Chat still works.

See Computer host and Seat Computer.

7. `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.

8. 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).

9. 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

10. 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.

​Desktop app (macOS)

​Log files

​Ports

​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. Seat Computer is off

​7. setup.sh stops on Docker

​8. Node / Python mismatch

​9. Ports already bound

​10. Encryption key changed

​Still stuck