Troubleshooting

Troubleshooting

relation "users" does not exist / empty database

Postgres started without the schema. The init script only runs when the data volume is empty. Make sure backend/init_postgresql_schema.sql is a file (Docker creates an empty directory there if the file was missing when the container started), then recreate the volume. This deletes all data:

docker compose down
docker volume rm shadowrealms-ai_postgresql_data
docker compose up -d postgresql
docker compose exec postgresql psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c '\dt'

Backend can't connect to the database

Check DATABASE_HOST=localhost in .env. The backend is on the host network, so postgresql (the service name) doesn't resolve.

Backend hangs at "Waiting for monitoring service"

The backend waits until the monitoring container has written data/logs/system_status.json. Check docker compose logs monitoring.

/ai ping shows "Raw reply: (empty)"

The model is spending its tokens on thinking. Set LM_STUDIO_REASONING_EFFORT=none in .env and run docker compose up -d backend. See AI Models.

Dice or combat prompts return "Error generating response"

Those go to Ollama (llama3.2:3b) first and don't fall back. Check systemctl status ollama and ollama list.

gpu_status is empty in monitoring

The container can't see the GPU. Install the NVIDIA container toolkit, run sudo nvidia-ctk runtime configure --runtime=docker, restart Docker, and check docker info | grep -i runtimes lists nvidia.

Registration says the invite code is invalid

The code isn't in backend/invites.json, or it already reached max_uses. See Configuration.

Can't open it from another device

nginx listens on all interfaces, so it's usually the firewall. Allow port 80 from your LAN only. See Installation step 8.

Changes to .env don't apply

docker compose restart keeps the old environment. Use docker compose up -d <service> to recreate it.

Backend Python changes don't apply

The source is mounted but Flask runs without the reloader. Run docker compose restart backend.

The page is blank after an update, or JS/CSS "refused" in the console

Rebuild the frontend: ./scripts/build-frontend.sh. If you edited nginx/nginx.conf, recreate nginx (docker compose up -d --force-recreate nginx): the config is mounted as a single file, and an edited copy isn't seen by a plain reload.

"Too many attempts" / locked out at login

Lockouts always expire (15–60 minutes). An admin can lift one right away in Admin → Logins & lockouts. Addresses you've signed in from before aren't affected by the account-wide lock. See Security.

Everyone was logged out after an update

Logins issued before the security update don't carry the new token version and are rejected once. Sign in again.