Troubleshooting

Check the relevant service and keep error details free of credentials.

The server does not start

Check application logs first. Missing database or Redis settings stop production startup. Confirm the runtime database role can connect and the migration role has the permissions needed to apply pending migrations.

For Docker Compose:

docker compose ps
docker compose logs --tail=100 app db redis

For a native Linux service:

sudo journalctl -u open-tabletop -n 100 --no-pager

The lobby opens but the table does not connect

Check WebSocket forwarding if using a reverse proxy. Refresh clients after updating the server. Check the room code, admission status, and whether the room still exists.

Authentication or uploads return 503

Check Redis connectivity and logs. Protected requests fail closed when the shared rate-limit service is unavailable. Do not switch production replicas to independent in-memory rate limits to hide the failure.

A control is missing or disabled

Check your room role and participation status. Library needs Helper access; table settings, fog, and scene loading need GM access; Add to Library and Save Scene need site administrator access. Spectating and time-out block gameplay even when your role normally permits it. Close an expanded hand tray if it hides Seat or Table Actions on a touch layout.

If a saved asset is missing, check Filters > Custom / All, By Collection, and Uncollected. Private assets are available to site administrators; other users need the asset published. Publishing a collection does not publish its members.

The table is full

The table has a 250-piece limit. Remove unused pieces or combine compatible cards/stacks before spawning more. Notecards also have a separate 16-card room limit, including hands and stack contents. Failed placement should retain the card or item you were trying to place.

A package upload fails

Check the proxy's request-size limit and available temporary storage. Only one package operation runs at a time per server process; retry a busy transfer after the other operation finishes. See Networking and HTTPS.

An administrator password stopped working

Bootstrap settings only create an administrator on an empty users table. They do not reset existing accounts. Use enrolled email recovery or a saved recovery code. To grant administrator access to an existing account from the server, use the command in Accounts and permissions.

Recovery emails do not arrive

Check PUBLIC_ORIGIN, SMTP host, port, sender authorization, credentials, and outbound connectivity. Check the recipient's spam folder. Recreate the Compose app container after changing its environment; restarting the old container does not load new values.

The password file must contain only the SMTP password, without a variable name or quotes. See Email recovery.

Uploaded assets are missing or unwritable

Confirm ASSETS_DIR points to the intended storage and the application user can access it. Check that mounted storage is available after reboot. A database restore must be paired with its uploaded files. For Proxmox NFS storage, follow the numeric ownership mapping in the installer guide.

A saved hand did not return

Rejoin with the original account. A new quick-join account is a different owner even if it uses the same display name. Ask a GM to check Unclaimed hands in Members.

Report a problem

Include the application version, installation method, browser, steps to reproduce, and relevant redacted logs in a GitHub issue. Remove passwords, connection strings, recovery codes, and private game data. Report suspected vulnerabilities through the private reporting instructions.

Compose ignores a setting or cannot read a secret

The bundled Compose file forwards only its declared environment keys. For TRUST_PROXY_HOPS, SESSION_TTL_DAYS, or AUTO_MIGRATE, add the Compose override, then recreate the app.

A startup permission error for /run/secrets/... can mean the host file is readable only by a different user. Follow secret-file permissions. Do not print passwords when collecting diagnostics.

Sources checked: README.md, docs/ACCOUNT_SECURITY.md, SECURITY.md. Reviewed September 29, 2026 against the working source. Published releases may differ; check the changelog for your version.