🔧 Troubleshooting

This section provides solutions for resolving issues you might encounter with Coolify. Pick the category that matches your problem.

Installation

Install script failed

Debug an installation that fails or completes without a working dashboard or containers.

Docker installation failed

Fix the Docker install step failing on non-LTS operating systems.

Applications

Bad Gateway (502)

Resolve 502 errors from wrong ports, host mapping, or an app bound only to localhost.

No Available Server (503)

Fix 503 errors from failed health checks, domain mismatches, or Traefik issues.

Gateway Timeout (504)

Fix 504 errors from custom network isolation or proxy timeouts that are too short.

Failed to get access token

Fix GitHub token errors during deployment caused by server clock drift.

Dashboard

Dashboard inaccessible

Restore access to the dashboard by checking the proxy, containers, and firewall.

Slow dashboard performance

Speed up a slow dashboard, often caused by Cloudflare Rocket Loader.

Docker

Expired GitHub Personal Access Token

Fix ghcr.io authentication errors by logging out or renewing an expired PAT.

Server

Connection unstable

Fix dropped connections caused by UFW or iptables rate-limit rules on port 22.

Server crash during build

Stop builds from overloading the server by offloading them to a build server.

2FA stopped working

Fix rejected two-factor codes by synchronizing the server clock with NTP.

Raspberry Pi crashes

Stabilize a Raspberry Pi that crashes under load on low-RAM models.

Server validation issues

Resolve server validation errors from malformed SSH keys or missing authorization.

DNS & Domains

Wildcard SSL certificates

Fix Coolify not using a wildcard SSL certificate for your domain.

Let's Encrypt not working

Fix Let's Encrypt failing to issue certificates from ports, DNS, or proxy interference.

Certificate resolver not found

Fix the "cert resolver doesn't exist" error from acme.json file permissions.

If you have a suggestion for a new troubleshooting guide or want to contribute, feel free to submit a pull request or open an issue with a detailed description in our GitHub docs repository.