Troubleshooting

Diagnose and fix common self-hosted NocoDB issues: startup, networking, SSL, database, attachments, and login.

Most self-hosting problems surface in the container logs and come down to a handful of causes: a port conflict, a database connection, a proxy or URL mismatch, or SSL. Start with the logs, then jump to the matching section below.

Start with the logs

cd nocodb            # your deployment directory
docker compose ps    # are all containers running and healthy?
docker compose logs -f nocodb

NocoDB prints its configuration and any fatal error on startup. docker compose ps shows whether a container is restarting (a crash loop) or stuck in an unhealthy state.

NocoDB won't start or keeps restarting

Symptom in logs	Likely cause	Fix
`ECONNREFUSED` or `could not connect to ... 5432`	Postgres not reachable	Confirm the `db` container is healthy, or that your external `NC_DB` host, port, and credentials are correct.
`password authentication failed`	Wrong database credentials	Fix the password in `docker.env` or `nocodb/db.json`, then `docker compose up -d`.
`requires PostgreSQL`	Running a license on SQLite or MySQL	License activation needs Postgres. See License activation.
Exits immediately, no clear error	Corrupt or version-mismatched data volume	Check you didn't point a newer Postgres major version at an older data volume. See Backups.

A port is already in use

With a domain, NocoDB runs behind Traefik on ports 80 and 443; local mode uses 8080.

sudo lsof -i :443    # find what's holding the port

Stop the conflicting service, or run NocoDB in local mode (leave the domain blank) behind your existing reverse proxy. See Bringing your own reverse proxy or SSL.

Links, redirects, or OAuth callbacks point to the wrong URL

If NocoDB generates http://localhost:8080 links, or login redirects break behind a proxy, the instance doesn't know its public URL.

Set NC_SITE_URL to your public-facing URL, for example https://nocodb.example.com.
If you terminate TLS at a proxy, forward the X-Forwarded-Proto and Host headers so NocoDB builds https:// links correctly.

See Frontend environment variables.

SSL certificate isn't issued (Let's Encrypt)

Traefik can't obtain a certificate. Check, in order:

Your domain's DNS A record points at the server's public IP.
Port 80 is open to the internet (Let's Encrypt validates over HTTP).
You used a real hostname, not an IP address (certificates can't be issued for bare IPs).
Run docker compose logs traefik and read the ACME error.

Attachments don't load or upload

Local storage: confirm the nocodb_data volume is mounted and the disk isn't full (df -h).
Broken links after enabling access control: turning on NC_ATTACHMENT_ACCESS_CONTROL_ENABLED switches to expiring pre-signed URLs, which makes previously shared public links stop working. See Storage environment variables.
S3 or MinIO: verify your NC_S3_* credentials, bucket, and region.

Data looks empty after an upgrade

Almost always the bind-mount to named-volume switch: the new compose file mounted fresh, empty volumes. Your data is still in the old ./postgres and ./nocodb directories. Follow Migrating from bind mounts to named volumes.

Locked out or need to reset the super admin

Set both variables together (NocoDB requires both to change either), then restart:

# in docker.env
NC_ADMIN_EMAIL=admin@example.com
NC_ADMIN_PASSWORD=a-strong-password

docker compose up -d

See Updating super admin credentials.

A license won't activate

See the License activation troubleshooting table. It covers activation failures, instance-ID changes, and paused features.

Still stuck?

Capture logs to share: docker compose logs --no-color > nocodb-logs.txt
Open an issue on GitHub, or reach the community on Discord.