Troubleshooting

Problems people actually hit running and developing Waterflow, and the fix.

Running the stack

I lost the setup code

It’s printed again on every start while the server has no admin: docker compose restart waterflow, then docker compose logs waterflow.

waterflow keeps restarting: the database isn't reachable

The database didn’t come up within two minutes. docker compose logs db. With your own database, check ADMIN_DATABASE_URL (owner login, host reachable from the container, sslmode).

permission denied to alter role, on every start after the first

With Supabase or another database whose owner isn’t a superuser, 0.1.4 and older start once, then stop at every later start with:

psycopg.errors.InsufficientPrivilege: permission denied to alter role
DETAIL:  Only roles with the SUPERUSER attribute may alter roles with the SUPERUSER attribute.

Update to 0.1.5 or newer: Updates, or on Google Cloud Run the update lines in Run it on Google Cloud Run. Nothing was changed in the database: the server stopped before doing anything. On Cloud Run, the version that was running keeps serving until it next sleeps; a failed deploy never takes traffic.

service "secrets" didn't complete successfully

docker compose logs secrets. A traceback there is a bug in the image; with a permissions error, the secrets volume belongs to someone else (it should start empty and be created by Compose).

The Overview fails, or saving a book or profile says the timezone isn’t known

Fixed for aliases like Asia/Saigon (what Windows browsers report): the server maps them to a name the database knows. A database made before that fix may hold an unknown name: on a local test stack, docker compose down -v.

403 origin_not_allowed

The browser is on a different address than the server, for example a copy of the web app served elsewhere, or a proxy that rewrites Host without setting X-Forwarded-Host. Open the web app from the server’s own address. In development, use npm run dev: its proxy sends X-Forwarded-Host.

401 not_signed_in on every call

The session ended: 30 days unused (or your own sign-out after inactivity), signed out elsewhere or from another device’s Profile and security, a password change on another device, a reset, or the admin disabled the account. Sign in again. On a fresh database (down -v), old browser sessions are gone too.

403 invite_required or invite_invalid when joining

The server takes new accounts by invite only; the code is wrong, used, revoked or expired. The admin makes a new one (or opens sign-up).

The one-click Update says it’s off, or fails

It needs COMPOSE_PROFILES=updater and docker compose up -d. The page shows the helper’s last error:

• “on a fixed version, not a branch”: the folder is on a release tag (staying on one version); git checkout main to follow releases again.
• A git pull error about local changes: someone edited a file in the folder. Settings belong in .env; git status shows what changed, git stash puts it aside.
• A git pull error that “untracked working tree files would be overwritten”: a file you made in the folder now comes with Waterflow (for example a .gitignore you added for .env, which Waterflow now ignores by itself). Delete or rename yours, then update again.

docker compose logs updater for more.

The dashboard says some transactions are “not included”

There’s no exchange rate for their currency yet. The rates job fetches them at a new server’s first start, then every day at its time; see below if it fails.

Exchange rates don’t update

Server admin, Daily jobs, shows the rates job’s last result; docker compose logs waterflow | grep -i rates has every line. A job that failed runs again an hour later, until it works.

• “no source’s HTTPS certificate was trusted” (in Python’s words CERTIFICATE_VERIFY_FAILED: unable to get local issuer certificate): something on this network replaces HTTPS certificates. Usually antivirus “HTTPS scanning” (common with Docker Desktop on Windows), or a company proxy or firewall. To see who, run this in the waterflow folder: a public authority (Google Trust Services, Let’s Encrypt) is normal; any other name is what’s in the way.

  docker compose exec waterflow python -c "import socket,ssl,tempfile; c=ssl.create_default_context(); c.check_hostname=False; c.verify_mode=ssl.CERT_NONE; s=c.wrap_socket(socket.create_connection(('open.er-api.com',443),timeout=10),server_hostname='open.er-api.com'); f=tempfile.NamedTemporaryFile('w',suffix='.pem',delete=False); f.write(ssl.DER_cert_to_PEM_cert(s.getpeercert(True))); f.close(); print(dict(x[0] for x in ssl._ssl._test_decode_cert(f.name)['issuer']))"
  

  Turn off the antivirus’s HTTPS scanning, or exempt Docker or these addresses: open.er-api.com, cdn.jsdelivr.net, latest.currency-api.pages.dev (and openexchangerates.org with OXR_APP_ID). On a company network, ask whoever runs it, or run the server somewhere else.

• “no source answered” with “no answer in time”, or a name that can’t be resolved: the container can’t reach the internet (DNS, a firewall).

Supabase’s logs show schema "pg_pgrst_no_exposed_schemas" does not exist

Every 32 seconds, with Supabase’s /rest-admin/v1/ready check answering 503: that’s Supabase’s own Data API, which Waterflow doesn’t use, when it’s turned off for the project. It’s harmless. To quiet it, follow Supabase’s note.

Development

dev.sh can’t reach the database on 5433

Something else uses the port, or the compose db was started without docker-compose.dev.yml. dev.sh restarts it with the override; docker compose ps db should show 127.0.0.1:5433->5432.

The web app shows a network error on npm run dev

The API isn’t on 127.0.0.1:8000 (start dev.sh), or set WATERFLOW_API=http://127.0.0.1:8080 for the compose stack.

Tests

Backup tests fail with a pg_dump version error

Your PATH finds an older pg_dump first. Prefix the test command with PATH=/usr/lib/postgresql/17/bin:$PATH.

Backups fail with an SSL error, with your own database

The database address asks for TLS (?sslmode=require) and the database doesn’t offer it. On a database across the internet, turn TLS on there; on the same machine or a private network, use ?sslmode=disable. Without sslmode, the server uses TLS when the database offers it.