Nia documentation · 4.0.0
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 needs the stable external URL to build setup, reset and verification links.
OIDC login fails
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 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.
Shopping or Recipes is missing
First check the server and client versions. V4 requires native clients 4.0.0 or newer. A native client bundles its own UI, so install the matching client update from your server. Check Settings → Modules on the correct account. Module visibility synchronizes per account and is separate from household membership or access to a particular collection.
An item is missing after reconnect
Confirm the account, server and current collection access before retrying changes. Check whether a project, list, cookbook or child was deleted or transferred, or a participant’s last access source was removed. Pending offline changes cannot override revoked access. Do not clear local app/browser storage while unsynchronized work still exists; capture sanitized reproduction details first.
An attachment quota changed after sharing
Usage follows the uploader’s current access to the containing task, rather than charging every participant. Losing the last access source releases that uploader’s charge; restored access makes retained uploads count again. Other participants can still read files when they can read the task, even with no upload allowance. Recipe title images are stored in SQLite and are outside Tasks attachment quotas. See Administration.
Recipe link import fails
The server must reach a public recipe page without a login. Private addresses, nonstandard ports, credential-bearing URLs and redirects to blocked destinations are rejected. Some websites block automated requests or publish incomplete recipe data; a supported site name is not a guarantee that every page imports perfectly.
Try the direct recipe URL and check server connectivity. If extraction remains incomplete, paste the recipe into BrainDump when enabled for the account, or create/edit the draft manually. A failed preview does not create a saved recipe. Missing source quantities or ingredient groups should be checked in the preview rather than treated as reliable inferred facts.
Recipe BrainDump is unavailable or fails
Verify global BrainDump enablement, the current user’s BrainDump permission and the LLM configuration. Recipe text/refinement does not need STT; a working transcription test alone does not prove the LLM can return a valid recipe response. Check proxy and provider timeouts, model output limits and the server log’s sanitized recipe BrainDump reason. The editor draft remains available after failure.
Retry after a busy/rate-limit response has cleared. Use a simpler recipe to distinguish model/schema failures from source-import issues. Never paste provider tokens, full private recipes, model responses or account information into public logs or issue reports.
Personal memory does not choose a destination
Memory is personal to the signed-in account and must be enabled in Settings → Memory. It learns deliberate destination choices from Tasks/Shopping entry, moves, BrainDump and recipe transfers. It proposes a destination only with sufficient evidence and current edit access. Conflicting or ambiguous history can leave fields unchanged; a missing suggestion is not a reason to force a guessed destination.
Check that the project/list and its section/store still exist and are accessible. Correct the destination deliberately to update the history. Reset removes shared destination learning for that account across Tasks and Shopping; it is not limited to the currently open module.
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 version, installation method, relevant sanitized logs and exact reproduction steps. Never post passwords, API keys, setup links or provider secrets.