Troubleshooting

First, look at what Qwest says. From your qwest folder:

docker compose ps
docker compose logs --tail 100 qwest

Qwest doesn’t start

The logs say…	Fix
set QWEST_VERSION in .env or pull access denied for qwest	QWEST_VERSION doesn’t match a loaded image. Run docker images qwest and use the version it lists.
set POSTGRES_PASSWORD in .env	Fill in the secrets: Install, step 4.
BETTER_AUTH_SECRET is not set (or another name)	That line in .env is empty.
waiting for the database… over and over	The database is still starting, or its password changed. Check docker compose logs postgres.
port is already allocated	Something else uses port 8080. Set QWEST_PORT=8081 (or another number).

I can’t sign in

• Open exactly the address in BETTER_AUTH_URL, including http/https and the port. The same server under another address (its IP, localhost) refuses sign-ins.
• Changed BETTER_AUTH_URL? Run docker compose up -d so Qwest picks it up.

Docs and graphs say they’re offline or don’t update live

Live editing uses a WebSocket at /collab. If you put your own web server in front of Qwest, make sure it passes WebSockets through. Caddy and Tailscale do this by themselves.

Uploads fail

• “Storage limit”: the workspace hit its limit. Raise it in Instance admin›Access or Workspaces.
• Server disk full: check Instance admin›Storage. Delete old files, grow the disk, or move uploads to cloud storage.
• Big files fail through a tunnel: some tunnels (like Cloudflare Tunnel’s free plan) limit upload size. Use Tailscale or a domain.

Phones can’t install the app

Phones need an https:// address. See Tailscale or a domain.

“The requested image’s platform (linux/amd64) does not match”

You’re on an ARM machine, like an Apple Silicon Mac. On a Mac, it still runs through Rosetta (see macOS). On an ARM VPS, rent an Intel/AMD one instead.

Still stuck?

Write to hello@qwest.dev with the output of docker compose logs --tail 100 qwest. Remove any secrets from it first.