Troubleshooting¶

A guide to diagnosing and fixing common problems with Dreadnought.

First Steps: Check the Logs¶

When something goes wrong, logs are almost always where you'll find the answer.

Docker Compose¶

# All services at once
docker compose logs -f

# Specific service (most useful)
docker compose logs api --tail 50
docker compose logs worker --tail 50
docker compose logs web --tail 50

# Follow live
docker compose logs -f api

Systemd¶

sudo journalctl -u dreadnought-api -n 50
sudo journalctl -u dreadnought-worker -n 50
sudo journalctl -u dreadnought-web -n 50

# Follow live
sudo journalctl -u dreadnought-api -f

Container / Service Problems¶

"Unable to open database file"¶

Error:

sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) unable to open database file

Cause: The ./data directory doesn't exist or the container user (UID 1000) can't write to it.

Fix:

docker compose down
mkdir -p ./data
chmod 777 ./data
docker compose up -d

Container is "unhealthy" or keeps restarting¶

Check what's happening:

docker compose ps                # See status
docker compose logs api          # Check for error messages

Common causes:

Cause	How to identify	Fix
Missing env variable	Log shows `KeyError` or `None` type error	Check `.env` has all required variables
Wrong `CF_API_TOKEN`	Log shows `Authentication error` or `403`	Verify token in Cloudflare dashboard
Database permission error	`unable to open database file`	`chmod 777 ./data`
Port conflict	`address already in use`	Change port in `docker-compose.yml`

"Address already in use" on port 8081 or 8082¶

Cause: Another service is using that port.

Find what's using it:

# Linux
sudo ss -tlnp | grep 8081
sudo lsof -i :8081

# macOS
sudo lsof -i :8081

Fix options: 1. Stop the conflicting service 2. Change Dreadnought's port in docker-compose.yml: yaml api: ports: - "9081:8000" # Use a different host port

Worker container exits immediately¶

Check logs:

docker compose logs worker

Common causes: - Missing CF_API_TOKEN in .env - Database not yet initialized (worker starts before API)

Fix:

# Verify .env has all required variables
cat .env

# Restart with proper order (API first)
docker compose down
docker compose up -d

Authentication Problems¶

"Invalid credentials" when logging in¶

Double-check you're using the exact ADMIN_EMAIL and ADMIN_PASSWORD from your .env
Passwords are case-sensitive
If you changed the password in .env after first run, restart the API: bash docker compose restart api

Session keeps expiring / getting logged out¶

Sessions expire after 30 minutes. This is intentional. If you need longer sessions, this is currently not configurable.

Forgot the admin password¶

Edit your .env file, change ADMIN_PASSWORD, and restart the API. The password is re-hashed and updated in the database on startup:

nano .env
# Update ADMIN_PASSWORD

docker compose restart api

Cloudflare / DNS Problems¶

"Failed to resolve zone_id for domain"¶

Error in logs:

Failed to resolve zone_id for domain example.com

Causes and fixes:

Cause	Fix
Token missing `Zone → Zone → Read` permission	Add this permission to the Cloudflare API token
Domain not in your Cloudflare account	Verify the domain is active in Cloudflare
Domain name has a typo	Double-check the domain name in Dreadnought's Domains page
Wrong API token	Verify `CF_API_TOKEN` in your `.env` matches the token in Cloudflare

Verify the token has correct permissions:

curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer YOUR_CF_API_TOKEN" \
  | python3 -m json.tool

"CNAME record exists, cannot create A/AAAA record"¶

Cause: There's already a CNAME record at that hostname in Cloudflare. DNS doesn't allow a CNAME to coexist with an A or AAAA record at the same name.

Fix: 1. Log into Cloudflare 2. Go to DNS → Records 3. Find and delete the CNAME record at that hostname 4. Try creating the record in Dreadnought again

"Rate limit exceeded"¶

Error:

Cloudflare API rate limit exceeded

What happens: The app handles this automatically with exponential backoff — it waits and retries. This message in the log is informational.

If it persists: - Increase POLL_INTERVAL_SECONDS to reduce API calls (e.g. 600 instead of 300) - Check if another application is using the same API token simultaneously - Cloudflare's rate limit is 1200 requests per 5 minutes per token

Records not updating when IP changes¶

Check:

Is the worker running? bash docker compose ps # worker should show as "running"
Is the worker detecting the IP change? bash docker compose logs worker --tail 30
Check the audit log in the Dreadnought UI — is there a recent bulk_sync entry?
Manually trigger a sync via the dashboard or API: bash # Trigger sync (replace with your session cookie) curl -X POST http://localhost:8081/api/sync -b cookies.txt
Verify the IP is actually different: bash curl https://api.ipify.org

DNS record updated in Dreadnought but not in Cloudflare¶

Check the API logs for any Cloudflare API errors:

docker compose logs api --tail 50

Look for cloudflare or cf_client in the logs.

Common causes: - CF_API_TOKEN expired or was revoked — create a new one - Cloudflare API is temporarily unavailable — syncs will retry - Token doesn't have Zone → DNS → Edit permission

Frontend / UI Problems¶

Dashboard loads but API calls fail (browser shows network errors)¶

Cause: NEXT_PUBLIC_API_URL is wrong or the browser can't reach the API.

Diagnose: 1. Open browser DevTools (F12) → Network tab 2. Click on a failing request and look at the URL it's trying to reach 3. Compare that to what NEXT_PUBLIC_API_URL is set to

Fix: - If accessing from a different machine, NEXT_PUBLIC_API_URL must be the server's IP or domain, not localhost - Update docker-compose.yml and rebuild: yaml web: environment: - NEXT_PUBLIC_API_URL=http://192.168.1.100:8081 bash docker compose up -d --build

Cause: API not reachable from the browser. Same as above — check NEXT_PUBLIC_API_URL.

Also check:

# Is the API actually running?
docker compose ps
curl http://localhost:8081/health

Blank page or JavaScript errors in the browser¶

Cause: Frontend build failed or NEXT_PUBLIC_API_URL is set to something that breaks the build.

Fix:

# Check web container logs
docker compose logs web

# Force a full rebuild
docker compose down
docker compose up -d --build

Dark mode not working¶

Dark mode is system-aware (follows your OS preference) with a manual toggle. If it's not toggling: - Clear browser cache and reload - Try a hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)

Performance Problems¶

Dashboard is slow to load¶

Common causes:

Container on low-memory device — check resource usage: bash docker stats
SQLite database is large — the audit log grows over time. Currently there's no built-in pruning; you can manually delete old entries: bash sqlite3 ./data/ddns.db "DELETE FROM audit_log WHERE ts < datetime('now', '-90 days');" sqlite3 ./data/ddns.db "VACUUM;"
Slow disk on Raspberry Pi — SD cards are slow. Consider an SSD.

Worker sync is slow¶

Normal: A sync cycle touching 10+ records against the Cloudflare API can take a few seconds.

If it's very slow (>30 seconds): Cloudflare may be rate-limiting or experiencing latency. Check the worker logs:

docker compose logs worker --tail 30

Common Error Reference¶

Error message	Likely cause	Fix
`unable to open database file`	`./data` doesn't exist or isn't writable	`mkdir -p ./data && chmod 777 ./data`
`Authentication error 401`	Invalid or expired Cloudflare API token	Verify/recreate the token
`403 Forbidden` from Cloudflare	Token lacks required permissions	Add `Zone:Zone:Read` and `Zone:DNS:Edit`
`CNAME conflict`	CNAME exists at that hostname	Delete the CNAME in Cloudflare
`Failed to resolve zone_id`	Token lacks Zone:Read or wrong domain name	Check token permissions and domain spelling
`Connection refused` to API	API container not running	`docker compose up -d`
`Network error` in browser	Wrong `NEXT_PUBLIC_API_URL`	Update to correct API URL and rebuild
`Rate limit exceeded`	Too many API calls	Increase `POLL_INTERVAL_SECONDS`
Container `Exited (1)`	Startup error — check logs	`docker compose logs api`

Getting More Help¶

If you've gone through this guide and still can't solve the problem:

GitHub Discussions — Ask a question — good for "how do I..." questions
GitHub Issues — Report a bug — include the relevant log output

When reporting a bug, include: - Your deployment method (Docker Compose / Coolify / systemd / etc.) - Operating system and Docker version - Relevant log output (docker compose logs api --tail 50) - What you expected vs. what happened

Troubleshooting¶

First Steps: Check the Logs¶

Docker Compose¶

Systemd¶

Container / Service Problems¶

"Unable to open database file"¶

Container is "unhealthy" or keeps restarting¶

"Address already in use" on port 8081 or 8082¶

Worker container exits immediately¶

Authentication Problems¶

"Invalid credentials" when logging in¶

Session keeps expiring / getting logged out¶

Forgot the admin password¶

Cloudflare / DNS Problems¶

"Failed to resolve zone_id for domain"¶

"CNAME record exists, cannot create A/AAAA record"¶

"Rate limit exceeded"¶

Records not updating when IP changes¶

DNS record updated in Dreadnought but not in Cloudflare¶

Frontend / UI Problems¶

Dashboard loads but API calls fail (browser shows network errors)¶

Login page shows but clicking "Log In" does nothing¶

Blank page or JavaScript errors in the browser¶

Dark mode not working¶

Performance Problems¶

Dashboard is slow to load¶

Worker sync is slow¶

Common Error Reference¶

Getting More Help¶