# Troubleshooting

> Part of the NocoDB documentation (Self-hosting). Index of all pages: https://nocodb.com/llms.txt. Any docs page is available as Markdown by adding `.md` to its URL.

URL: https://nocodb.com/docs/self-hosting/troubleshooting
Last updated: 2026-10-03

Find and fix common problems with self-hosted NocoDB: startup, network, SSL, database, attachments and login.

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

```bash
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

| Symptom in logs                                   | Likely cause                                          | Fix                                                                                                                                                  |
| ------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ECONNREFUSED` or `could not connect to ... 5432` | NocoDB cannot connect to Postgres                     | Make sure that the `db` container is healthy. For an external database, make sure that the `NC_DB` host, port and credentials are correct.           |
| `password authentication failed`                  | The database credentials are wrong                    | Correct the password in `docker.env` or `nocodb/db.json`. Then run `docker compose up -d`.                                                           |
| `requires PostgreSQL`                             | A license runs on SQLite or MySQL                     | License activation needs Postgres. Refer to [License activation](/docs/self-hosting/license-activation).                                             |
| NocoDB stops immediately and shows no clear error | The data volume is corrupt or has a different version | Make sure that you did not use a newer Postgres major version with an older data volume. Refer to [Backups](/docs/self-hosting/maintenance/backups). |

## 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**.

```bash
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](/docs/self-hosting/installation/single-server#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](/docs/self-hosting/environment-variables#frontend).

## 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](/docs/self-hosting/environment-variables#storage).
* **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](/docs/self-hosting/maintenance/upgrading#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:

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

```bash
docker compose up -d
```

Refer to [Updating super admin credentials](/docs/self-hosting/environment-variables#updating-super-admin-credentials).

## A license won't activate

Refer to the [License activation troubleshooting](/docs/self-hosting/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:

```bash
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:

```bash
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](https://github.com/nocodb/nocodb/issues), or ask the community on the [NocoDB forums](https://community.nocodb.com/).

---

## Related pages

- [Self-Hosting](https://nocodb.com/docs/self-hosting.md): Self-host NocoDB on your own infrastructure and keep full control of your data.
- [Environment Variables](https://nocodb.com/docs/self-hosting/environment-variables.md): Set environment variables to configure a self-hosted NocoDB instance: database, storage, authentication, cache, rate limits and more.
- [Purchasing a License](https://nocodb.com/docs/self-hosting/purchase-license.md): Purchase a Business or Scale plan license for your self-hosted NocoDB instance through NocoDB Cloud.
- [Activating a License](https://nocodb.com/docs/self-hosting/license-activation.md): Activate a self-hosted NocoDB license with the standard, airgapped or fully offline method.
- [White Label](https://nocodb.com/docs/self-hosting/white-label.md): Replace the NocoDB branding on your self-hosted instance with your own product name, logos, favicon, brand color, email branding and support contact.
- [Migration Guide](https://nocodb.com/docs/self-hosting/migration-guide.md): Migrate a self-hosted NocoDB instance from a non-Postgres database to PostgreSQL so you can activate a paid license without losing data.
- [License](https://nocodb.com/docs/self-hosting/license.md): The NocoDB Sustainable Use License (SUL), its Fair-Code principles, and when you need a commercial license.
- [FAQs](https://nocodb.com/docs/self-hosting/FAQs.md): Answers to common questions about self-hosted NocoDB: what the Community Edition includes, upgrades, shifted timestamps and instance details.