Troubleshooting

This page covers general server issues. For playback-specific problems (buffering, codec errors, HDR), see Streaming Troubleshooting.

Can’t access the web UI

Symptoms: Browser shows “connection refused” or times out when navigating to http://localhost:3000.

Check the basics:

Verify the container is running: docker compose ps
Check logs for startup errors: docker compose logs dubby
Confirm the port mapping is correct in your docker-compose.yml — the right side must match Dubby’s PORT (default 3000)

Common causes:

Cause	Fix
Container is restarting in a loop	Check logs for the error. Usually a missing env var or database issue
Port conflict	Another service is using port 3000. Change the host port: `"8080:3000"`
Firewall blocking access	Allow the port: `sudo ufw allow 3000/tcp` or equivalent
Bound to wrong interface	Set `HOST=0.0.0.0` (default) to listen on all interfaces

Container won’t start

Check the logs first:

docker compose logs dubby --tail 50

Common errors:

Error	Cause	Fix
`SIGNING_SECRET is required`	Missing required environment variable	Add `SIGNING_SECRET` to your `.env` file. Generate one: `openssl rand -hex 32`
`EACCES: permission denied`	Volume permissions	Ensure the data directory is owned by UID 1000: `sudo chown -R 1000:1000 /path/to/data`
`SQLITE_CANTOPEN`	Database path doesn’t exist	Verify `DUBBY_DATA_DIR` points to a valid, writable directory
`ECONNREFUSED 127.0.0.1:6379`	Valkey not running or not reachable	Ensure Valkey is in your Docker Compose file and on the same network

Database locked errors

Symptoms: Logs show SQLITE_BUSY or database is locked.

SQLite locks the entire database during writes. This can happen when:

A long-running scan or metadata refresh holds a write lock
A backup process has the database open
Multiple Dubby instances share the same database file

Solutions:

Wait for any running scans or workflows to complete
If using hot backups, use SQLite’s .backup command instead of copying files directly (see Backups)
Never run two Dubby containers pointing at the same database file

Media not appearing after scan

Symptoms: You’ve added files but they don’t show up in the library.

Check the scan completed — Look at the dashboard for active scans, or check logs for scan errors
Verify the volume mount — Files inside the container must be under the path you configured as a library source:
Terminal window
```
docker compose exec dubby ls /media/movies
```
Check file naming — Files must follow the expected folder structure. The most common issue is missing year in the folder name: Movie Name (2024)/Movie Name (2024).mkv
Check file permissions — The Dubby process (UID 1000) must be able to read the media files:
Terminal window
```
docker compose exec dubby ls -la /media/movies
```

High memory usage

Dubby’s memory usage scales with library size and active transcodes.

Typical usage:

Base: ~200–400 MB (server + web)
Per active transcode: ~100–300 MB depending on resolution
Large libraries (10,000+ items): +200–500 MB for metadata cache

If memory is unexpectedly high:

Check for stuck transcodes: docker compose logs dubby | grep transcode
Restart the container to clear accumulated caches: docker compose restart dubby
Set a memory limit in Docker Compose to prevent runaway usage:
```
services:
  dubby:
    mem_limit: 4g
```

Valkey connection issues

Symptoms: Logs show ECONNREFUSED errors for Redis/Valkey, or background jobs (scans, transcodes) don’t run.

Verify Valkey is running: docker compose ps valkey
Check the connection URL — Default is redis://valkey:6379. If you renamed the Valkey service in Docker Compose, update REDIS_URL to match
Check the network — Both containers must be on the same Docker network. Docker Compose handles this automatically if they’re in the same file

Enabling debug logs

For more detailed logging when diagnosing issues:

# Set log level to debug
DUBBY_LOG_LEVEL=debug docker compose up dubby

Debug logs include request timings, database queries, and detailed error traces. Don’t leave debug logging on in production — it generates a lot of output and may include sensitive information.

Checking server health

Use the built-in health endpoints to verify the server is functioning:

# Basic health
curl http://localhost:3000/health/

# Database connectivity
curl http://localhost:3000/health/ready

If /health/ready returns 503, the database is unreachable. Check the database file exists and has correct permissions.