Troubleshooting

Most self-hosting problems show in the container logs. They usually have one of these causes: a port conflict, a database connection, a proxy or URL mismatch, or SSL. Read the logs first. Then go to the section below that matches the problem.

Start with the logs

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

At startup, NocoDB prints its configuration and all fatal errors. docker compose ps shows if a container restarts again and again (a crash loop) or stays unhealthy.

NocoDB won't start or keeps restarting

A port is already in use

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

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

Do one of these:

• Stop the service that uses the port.
• Run NocoDB in local mode (leave the domain empty) behind your current reverse proxy. Refer to Bringing your own reverse proxy or SSL.

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

Sometimes NocoDB makes http://localhost:8080 links, or login redirects fail behind a proxy. This occurs when the instance does not know its public URL.

• Set NC_SITE_URL to your public URL, for example https://nocodb.example.com.
• If a proxy ends the TLS connection, forward the X-Forwarded-Proto and Host headers. NocoDB then makes correct https:// links.

Refer to Frontend environment variables.

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

Traefik cannot get a certificate. Do these checks in this order:

1. Make sure that the DNS A record of your domain points to the public IP of the server.
2. Make sure that port 80 is open to the internet. Let's Encrypt does its validation over HTTP.
3. Make sure that you use a real hostname, not an IP address. Let's Encrypt cannot issue certificates for bare IP addresses.
4. Run docker compose logs traefik and read the ACME error.

Attachments don't load or upload

• Local storage: Make sure that the nocodb_data volume is mounted and that the disk has free space (df -h).
• Broken links after enabling access control: When you turn on NC_ATTACHMENT_ACCESS_CONTROL_ENABLED, NocoDB uses pre-signed URLs that expire. Public links that you shared before then stop working. Refer to Storage environment variables.
• S3 or MinIO: Make sure that your NC_S3_* credentials, bucket and region are correct.

Data looks empty after an upgrade

The cause is almost always the change from bind mounts to named volumes. The new compose file mounted new, 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 the two variables together. NocoDB changes neither variable unless you set both. Then restart:

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

docker compose up -d

Refer to Updating super admin credentials.

A license won't activate

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

License activation fails behind an HTTP proxy

Problem: Your instance is behind an HTTP forward proxy. From inside the container, a curl test to https://app.nocodb.com/api/v1/on-premise/agent is successful. But license activation in the UI fails with "License activation failed. Please verify your license key and try again."

Cause: curl uses HTTP_PROXY / HTTPS_PROXY automatically. NocoDB runs on Node.js, which ignores these variables by default. NocoDB tries a direct connection to app.nocodb.com, and your firewall blocks it. Thus the curl test passes, but activation fails.

Fix: Add these environment variables to the NocoDB container (and to the worker, if it is separate). Then restart:

NODE_USE_ENV_PROXY=1
HTTPS_PROXY=http://<proxy-host>:<port>
HTTP_PROXY=http://<proxy-host>:<port>
NO_PROXY=localhost,127.0.0.1,<db-host>,<redis-host>

To make sure that Node.js connects through the proxy, run this command inside the container:

node --use-env-proxy -e "fetch('https://app.nocodb.com/api/v1/on-premise/agent',{method:'POST',headers:{'content-type':'application/json'},body:'{}'}).then(r=>console.log('HTTP',r.status)).catch(e=>console.error('FAILED',e.cause?.code||e.message))"

HTTP 400 shows that Node.js gets to the license endpoint through the proxy. The 400 is expected, because the test body is empty. License activation then works as usual.

Still stuck?

• To save the logs to share, run docker compose logs --no-color > nocodb-logs.txt.
• Open an issue on GitHub, or ask the community on the NocoDB forums.