Common Issues

Real problems, real fixes. If you hit something not listed here, check the logs first — the error message usually tells you what's wrong.

Installation

pnpm install fails with network errors

Symptom: ERR_PNPM_META_FETCH_FAIL or ETIMEDOUT.

Cause: Network issue, DNS problem, or npm registry unreachable.

Fix:

ping registry.npmjs.org
curl -I https://registry.npmjs.org

If either fails, check your internet connection. If DNS is stale:

sudo systemctl restart NetworkManager

Then retry:

pnpm install

If it still fails, clear the cache:

pnpm store prune
pnpm install

Postgres container is unhealthy

Symptom: docker compose ps shows unhealthy for soc_postgres.

Cause: Port 5433 is already in use, or the data volume is corrupted.

Fix: Check the port:

ss -lntp | grep 5433

If something else is using it, change the port in docker-compose.yml and update DATABASE_URL in both .env and apps/web/.env.local.

If the port is free, check the logs:

docker compose logs postgres

Common causes: bad password in docker/.env, insufficient disk space.

Migration fails with "relation already exists"

Symptom: Running pnpm drizzle-kit migrate errors on an existing table.

Cause: The database has partial migrations — likely from an aborted run.

Fix: Check which migrations have run:

docker exec soc_postgres psql -U soc -d soc_solo \\
  -c "SELECT * FROM drizzle.__drizzle_migrations;"

Compare to the files in packages/db/drizzle/. If they disagree, the safest fix is to drop and recreate the database:

docker exec soc_postgres psql -U soc -d postgres \\
  -c "DROP DATABASE soc_solo;"
docker exec soc_postgres psql -U soc -d postgres \\
  -c "CREATE DATABASE soc_solo;"
cd packages/db
pnpm drizzle-kit migrate

Warning: this destroys all data.

Seed fails with "user already exists"

Symptom: pnpm seed:user prints "User already exists."

Cause: The owner account was already created.

Fix: This is intentional. The seed script is idempotent — it doesn't overwrite existing users. If you need to change the password:

SEED_EMAIL=you@example.com SEED_PASSWORD='new-password' pnpm seed:user

The script updates the password on an existing user.

Cause: Multiple possibilities.

Fix: Check in this order:

AUTH_SECRET mismatch. If you changed AUTH_SECRET after seeding, sessions are invalid. Re-seed the password.

Wrong email. SEED_EMAIL might have been different. Check the users table:

docker exec soc_postgres psql -U soc -d soc_solo \\
  -c "SELECT email FROM users;"

Rate limited. Wait 15 minutes, or clear the Redis key:
```
docker exec soc_redis redis-cli -a <password> FLUSHDB
```
Warning: this clears all Redis data including sessions.

"Too many attempts" lockout

Cause: Login rate limiter — 5 attempts per 15 minutes.

Fix: Wait. Or clear Redis:

docker exec soc_redis redis-cli -a <password> \\
  --scan --pattern "ratelimit:*" | xargs -r \\
  docker exec -i soc_redis redis-cli -a <password> DEL

TOTP

TOTP codes always rejected

Cause: Clock drift between your device and the server.

Fix: TOTP depends on accurate time. Enable NTP sync:

sudo systemctl enable systemd-timesyncd
sudo systemctl start systemd-timesyncd
timedatectl status

If your phone is the problem, sync its clock in Settings.

Lost TOTP device, still have recovery codes

Fix: At login, when the TOTP prompt appears, click Use recovery code. Enter one of your ten codes. The code is consumed.

Once logged in, re-enroll TOTP with a new device from Settings → Security.

Lost TOTP device AND recovery codes

Fix: Direct database access is required:

docker exec -it soc_postgres psql -U soc -d soc_solo

Then:

UPDATE users SET totp_enabled = false, totp_secret = NULL
WHERE email = 'you@example.com';

DELETE FROM user_recovery_codes
WHERE user_id = (SELECT id FROM users WHERE email = 'you@example.com');

TOTP secret can't be decrypted

Symptom: Logs show "Failed to decrypt TOTP secret" or similar.

Cause: TOTP_ENCRYPTION_KEY was changed after enrollment.

Fix: Restore the original key from your password manager. If lost, use the recovery procedure above.

WebAuthn

"Security key not recognized"

Fix:

Try a different USB port
Plug directly into the machine, not a hub
Ensure the key is FIDO2/WebAuthn capable
If multiple keys are plugged in, remove all but one

Touch ID doesn't appear

Fix: On macOS, enable Touch ID for the browser in System Settings → Touch ID & Passwords. Restart the browser after.

WebAuthn origin mismatch

Symptom: Browser says "origin mismatch" or "wrong RP ID."

Cause: WEBAUTHN_RP_ID or WEBAUTHN_ORIGIN doesn't match the actual URL.

Fix: Edit apps/web/.env.local:

WEBAUTHN_RP_ID=localhost
WEBAUTHN_RP_NAME=ATHELOS
WEBAUTHN_ORIGIN=http://localhost:3000

Restart the web app. Existing WebAuthn credentials become invalid if you change these — you'll need to re-register.

Application

Page is blank or unstyled

Symptom: Content loads but no CSS, or a white page.

Cause: Build cache is stale after a config change.

Fix:

cd apps/site  # or apps/web
rm -rf .next
cd ../..
pnpm dev

Dev server hangs on "Compiling"

Cause: Stuck Turbopack or corrupted cache.

Fix:

pkill -f "next dev"
cd apps/site
rm -rf .next
cd ../..
pnpm dev:site

Hydration mismatch errors

Symptom: Console shows "Hydration failed because the initial UI does not match."

Cause: Server renders one thing, client renders another. Usually a component that reads browser-only state (localStorage, window).

Fix: Check the console for the specific component. Common culprits: date formatting, random IDs, components reading window at render time.

If you added a component recently, that's the suspect. Wrap browser-only reads in useEffect or use a mounted guard.

"Module not found" after install

Symptom: Import fails even though the package is in package.json.

Fix:

pnpm install
rm -rf .next
pnpm dev

If the error persists, the package might have a wrong name or path. Check node_modules/<package>/package.json exists.

Database

"relation does not exist"

Cause: Migrations haven't been applied.

Fix:

cd packages/db
pnpm drizzle-kit migrate

Slow queries

Cause: Missing indexes, or the database has grown large.

Fix: Check the slow queries:

docker exec soc_postgres psql -U soc -d soc_solo -c "
SELECT query, calls, mean_exec_time
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 10;"

If pg_stat_statements isn't enabled:

docker exec soc_postgres psql -U soc -d soc_solo \\
  -c "CREATE EXTENSION IF NOT EXISTS pg_stat_statements;"

Then enable it in postgresql.conf and restart the container.

Evidence

Upload fails with "disk full"

Fix: Check disk space:

df -h
docker system df

Clean up Docker:

docker system prune
docker volume prune

Warning: volume prune removes unused volumes. Check first with docker volume ls.

MinIO errors

Symptom: Evidence uploads fail. Browser console shows 500.

Fix: Check MinIO is running:

docker compose ps
curl http://localhost:9000/minio/health/live

Check credentials match between docker/.env and apps/web/.env.local.

AI

Ollama connection refused

Symptom: AI status shows "offline."

Fix:

curl http://localhost:11434/api/tags

If this fails, start Ollama:

sudo systemctl start ollama

If Ollama isn't installed, see AI: overview.

Model not found

Symptom: Chat or embeddings fail with "model not found."

Fix:

ollama pull llama3.2:3b
ollama pull nomic-embed-text

Semantic search returns nothing

Cause: No embeddings generated yet, or Ollama isn't reachable.

Fix: From Settings → AI → Embeddings, click Reindex all.

Or via CLI:

pnpm reindex:embeddings

RAG chat is very slow

Cause: Model too large for your hardware.

Fix: Switch to a smaller model:

ollama pull llama3.2:1b

Edit apps/web/.env.local:

OLLAMA_MODEL=llama3.2:1b
OLLAMA_NUM_CTX=1024

Restart the web app.

Backups

Backup script fails with "command not found: restic"

Fix: Install restic:

sudo apt install restic

Backup fails with B2 auth error

Cause: Wrong credentials in backups/.env.

Fix: Verify:

cd backups
source .env
echo "Repo: $RESTIC_REPOSITORY"
echo "Account: $B2_ACCOUNT_ID"

The B2_ACCOUNT_ID should be an Application Key ID, not your master B2 account ID.

free -h
df -h
docker stats

On a 4 GB machine, running Ollama + Postgres + Redis + MinIO + Meilisearch + Next.js is tight. Consider:

Stop Ollama when not using AI features
Increase swap
Move to a machine with more RAM

Dev server is slow to compile

Cause: Turbopack cache miss or large dependency tree.

Fix:

cd apps/site
rm -rf .next
cd ../..
pnpm dev:site

First compile is always slow. Subsequent ones are fast.

Docker

"Cannot connect to the Docker daemon"

Fix:

sudo systemctl start docker
sudo systemctl status docker

If Docker isn't installed, see the Installation guide.

Port already in use

Symptom: docker compose up fails with "port is already allocated."

Fix: Find what's using the port:

ss -lntp | grep <port>

Either stop the conflicting service or change the port mapping in docker-compose.yml.

Docker containers restart repeatedly

Cause: Configuration error or missing dependency.

Fix: Check the logs:

docker compose logs <service>

Common causes: bad env file, insufficient memory, corrupted volume.

Getting more help

If your issue isn't here:

Check the logs — journalctl, docker compose logs, browser console
Check the audit log — it records what the app tried to do
Check the repository's GitHub issues (if public)
Check docs/ in the repo — additional troubleshooting notes may be there

Include in any bug report:

The exact error message
The command or action that triggered it
What you expected to happen
Your environment (OS, Docker version, RAM)

Where to go next

FAQ — 20 common questions
Reference: CLI — commands mentioned here
Security — threat model and hardening

Common Issues

On this page