nia-todo documentation

Troubleshooting

Find logs and resolve common startup, proxy, storage, passkey and provider problems.

Start with logs

Docker

docker compose ps
docker compose logs --tail=250 nia-todo

Debian or Ubuntu

sudo systemctl status nia-todo
sudo journalctl -u nia-todo --since today

Verify the local server before debugging DNS or TLS:

curl -v http://127.0.0.1:8753/api/instance

The container starts with an empty setup page

The original persistent volume is missing or mounted at the wrong path. The official image stores all runtime data in /data; verify the volume mapping and NIA_TODO_DATA_DIR.

Do not continue setup if you expected existing data. Stop the container and attach the correct volume first.

Permission denied under /data

The container runs as UID 10001. For a host bind mount, grant that UID write access to the directory. Named Docker volumes are initialized automatically.

Passkey registration fails

Check all of the following:

the instance is opened through HTTPS, except for localhost development
Public base URL exactly matches the browser/native server origin
no alternate hostname or raw IP is being used
the reverse proxy forwards the original host and scheme

Passkeys created for one hostname cannot be used as if they belonged to another.

Realtime updates do not arrive

Ensure the reverse proxy supports WebSocket upgrade headers and does not cache API or WebSocket responses. Compare with the proxy examples.

Email links contain the wrong host

Set the public base URL in /admin. SMTP alone is not enough: nia-todo needs the stable external URL to build setup, reset and verification links.

Verify:

the issuer supports OIDC discovery over HTTPS
the redirect URI is exactly PUBLIC_BASE_URL/api/oidc/callback
client ID, secret and token authentication method match the provider
the provider returns a verified email claim
system time is synchronized on both services

BrainDump cannot reach a local provider

Inside Docker, 127.0.0.1 is the nia-todo container. Use the provider’s Compose service name on a shared network, or another address reachable from the container. Test the configured STT and LLM providers separately in /admin.

Administrator password lost

# Debian/systemd
sudo nia-todo-admin-password-reset
sudo systemctl restart nia-todo

# Docker Compose
docker compose exec nia-todo nia-todo-admin-password-reset

Existing administrator sessions are invalidated after the reset.

Still stuck?

Search existing GitHub issues. When opening a new issue, include the nia-todo version, installation method, relevant sanitized logs and exact reproduction steps. Never post passwords, API keys, setup links or provider secrets.