If you have ever run into a broken Coolify deployment and had no idea where to start, you are in the right place with this Coolify troubleshooting guide. Whether your installation failed, your domain isn’t loading, or your GitHub webhook stopped firing, this guide walks you through each issue step by step.

Before You Start: Check Your Server

Before diving into any specific error, you must do a quick sanity check on the server itself. Many Coolify issues depend on low resources or a dirty environment, not on Coolify itself.

Minimum server requirements include:

• 2 CPU cores
• 2 GB RAM. 4 GB recommended for real workloads.
• 30+ GB disk space.
• Ubuntu 20.04 LTS, 22.04 LTS, 24.04 LTS, or Debian 12.

First, run the commands below to verify disk space, memory usage, and check if Docker is running:

# Check disk space
df -h

# Check memory usage
free -h

# Check if Docker is running
sudo systemctl status docker

If the disk is above 85%, you must clean up before doing anything else:

docker system prune -a --volumes -f
du -sh /data/coolify/*

If you are on low resources or have a messy server, the best fix is to start fresh on a clean Linux VPS server. A fresh Ubuntu 24.04 LTS VPS removes all the noise so your Coolify install succeeds on the first try.

Once you have checked your server, you can proceed to the following steps to dive into the Coolify troubleshooting guide.

Problem 1. Docker Installation Fails During Coolify Setup

The symptom of this issue is that the Coolify install script stops at the installing Docker step. You see no Docker after the script finishes, or the script exits without any clear error.

This happens because the official Coolify install script only works automatically on Ubuntu LTS versions. If you are on a non-LTS Ubuntu version like 24.10, the Docker install step fails silently.

To fix this issue, you can use the following options:

Option A: Switch to an LTS OS (Recommended)

It is recommended to use Ubuntu 22.04 LTS or Ubuntu 24.04 LTS. These are the most tested, and the install script handles Docker automatically.

Option B: Install Docker manually first, then run Coolify

If you must stay on a non-LTS OS, you can install Docker 24+ manually before running the Coolify script:

# Remove old Docker packages
sudo apt-get remove docker docker-engine docker.io containerd runc

# Add Docker's official GPG key
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add Docker repo
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine 24+
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Verify
docker --version

Once Docker is confirmed working, run the Coolify install script:

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash

Verify Docker is running after install:

sudo systemctl status docker
docker ps

Problem 2. Coolify Dashboard Won’t Open After Install

In this issue, you ran the install script successfully, but when you go to http://YOUR_IP:8000, the browser shows nothing, connection refused, or a timeout.

Check 1: Are the Coolify containers actually running?

First, you must check the Coolify containers if they are running:

docker ps --format "table {{.Names}}\t{{.Status}}"

You should see the following containers all UP and have a Healthy status:

coolify, coolify-proxy, coolify-db, coolify-redis, and coolify-realtime

If Coolify shows as unhealthy, restart it:

sudo systemctl restart docker
docker ps

Check 2: Is port 8000 open?

Coolify’s dashboard runs on port 8000 by default. You must check if it is accessible:

# From the server itself
curl -I http://localhost:8000

# Check what is using port 8000
sudo ss -tlnp | grep 8000

Make sure your cloud provider’s firewall, not just UFW, allows port 8000 inbound. Required ports for a fresh install are:

8000	#Coolify dashboard
6001	#Real-time communications
6002	#Terminal access
22	#SSH
80	#SSL cert generation (Let's Encrypt)
443	#HTTPS traffic

Important note about UFW: Docker bypasses UFW rules by modifying iptables directly. Always use your cloud provider’s firewall panel to manage ports; do not rely on UFW alone.

Check 3: Check the Coolify container logs

Also, you can check the Coolify container logs to find the issue:

docker logs coolify --tail 50
docker logs coolify-db --tail 50

Problem 3. DNS Not Resolving for Your Domain

You set a domain in Coolify, but the browser just times out, or you see a “This site can’t be reached” error. Your app is running, but the domain does not work. This is one of the most common issues covered in any Coolify troubleshooting guide, and it is almost always a DNS record problem.

Step 1: Verify your A record is set correctly

In your domain registrar or DNS panel, you need:

• An A record for your subdomain pointing to your server’s public IP.
• Optionally, a wildcard A record if you want Coolify to auto-generate subdomains.

Example DNS setup:

Type   Name        Value
A      @           YOUR_SERVER_IP
A      *           YOUR_SERVER_IP

Step 2: Check DNS propagation from the server

Check what your domain resolves to with the command below:

dig app.yourdomain.com +short

Or, you can use the nslookup:

nslookup app.yourdomain.com

Then, verify against a public DNS server:

dig app.yourdomain.com @8.8.8.8 +short

If dig returns your server IP, DNS is working. If it returns nothing or a wrong IP, the record is not set correctly or has not propagated yet. DNS changes can take a few minutes to a few hours, depending on TTL.

Step 3: Check if Coolify can validate the domain

When you enter a domain in Coolify’s Settings page and hit Save, it runs a DNS validation check. If it fails even though DNS looks right, make sure:

• You added https:// at the start of the domain in the Coolify settings.
• Ports 80 and 443 are open so the reverse proxy can answer requests.
• You are not blocking Coolify’s outbound HTTP checks with a strict firewall rule.

Problem 4. HTTPS Certificate Not Generating (Let’s Encrypt Fails)

The symptom of this issue is that your domain loads over HTTP but not HTTPS. Coolify shows an SSL error, the browser shows a certificate warning, or the Traefik or Caddy proxy logs show a Let’s Encrypt failure.

Check 1: Ports 80 and 443 must be open

Let’s Encrypt needs to reach your server on port 80 for HTTP and port 443 for TLS-ALPN-01. If either is blocked, SSL will never work.

Check if ports are open and listening:

sudo ss -tlnp | grep -E "80|443"

Test from outside, run from a different machine, or use an online port checker:

curl -I http://yourdomain.com

Check 2: Cloudflare proxy mode conflict

If your domain is behind Cloudflare with the orange cloud (proxy) turned on, Let’s Encrypt HTTP often fails because Cloudflare intercepts the validation request. Fix this by either:

• Temporarily setting the DNS record to DNS only (grey cloud) during cert generation, then switching back.
• Using a DNS challenge with a Cloudflare API key instead of the HTTP.

Check 3: Wrong or corrupted acme.json permissions

The file /data/coolify/proxy/acme.json stores your SSL certificates. If its permissions are wrong, Traefik cannot read or write it.

Check the file and its permissions:

ls -la /data/coolify/proxy/acme.json

Fix permissions:

sudo chmod 600 /data/coolify/proxy/acme.json

Check 4: Force regenerate the certificate

If the cert is corrupted or outdated, delete it and restart the proxy:

# Delete the old cert file
rm /data/coolify/proxy/acme.json

# Then restart the Coolify proxy from the dashboard:
# Go to: Coolify Dashboard > Your Server > Restart Proxy

Check 5: Wildcard SSL cert not being used

If you uploaded a custom wildcard certificate and Coolify is ignoring it:

• Make sure the .cert and .key files are in /data/coolify/proxy/certs/.
• The cert file must have a .cert extension, the key file must have .key. Rename .pem files if needed.
• After adding the cert in the Coolify proxy dashboard, click Restart Proxy.

Check 6: Rate limiting by Let’s Encrypt

If you see a 429 error in the proxy logs, Let’s Encrypt has rate-limited your server’s IP. This happens when too many cert requests are made in a short time. The fix is to wait. Let’s Encrypt rate limits reset after a few hours to 7 days.

# View proxy logs to find the exact error
docker logs coolify-proxy --tail 100

Problem 5. Git Webhook Not Triggering Deployments

You push code to GitHub or GitLab, but Coolify does not pick it up. The deployment does not start automatically. This is a classic issue in any Coolify troubleshooting guide because the webhook pipeline has multiple points of failure.

Step 1: Enable Auto Deploy in Coolify

First, make sure Auto Deploy is actually turned on:

• Open your application in Coolify.
• Go to the Advanced tab.
• Enable Auto Deploy.

For more details on how GitHub Auto Deploy works in Coolify, you can check the official Auto Deploy documentation.

Step 2: Set up the webhook in GitHub correctly

For self-hosted Coolify with a manual webhook, not using the GitHub App:

1. In Coolify, go to your app → Webhook page → copy the Deploy Webhook URL
2. In GitHub, go to your repo → Settings → Webhooks → Add webhook
3. Set:
   • Payload URL: your Coolify webhook URL
   • Content type: application/json
   • Secret: the webhook secret from Coolify
   • SSL verification: Enabled
   • Events: Just the push event
   • Active: Checked

Step 3: Check GitHub webhook delivery

In GitHub, go to Settings → Webhooks → Recent Deliveries. If you see a red sign, click it to see the response code and error. Common issues:

• 400 Bad Request: Webhook secret mismatch between GitHub and Coolify.
• 422 Unprocessable: Wrong content type, must be application/json.
• Connection timed out: Port 443 or 80 is blocked on your server.

Step 4: Make sure ports are open for GitHub

GitHub’s webhook servers need to reach your Coolify instance on ports 80 and 443. If your server has a strict firewall, you can allowlist GitHub’s webhook IPs:

# Get GitHub's webhook IP ranges
curl -s https://api.github.com/meta | jq '.hooks'

Step 5: GitHub App webhooks not working

If you are using the official GitHub App integration in Coolify and webhooks still do not fire, this is a known bug in some Coolify versions. The workaround is to switch from the GitHub App to a manual webhook setup as described in Step 2 above, or use the Coolify API with a GitHub Action:

# .github/workflows/deploy.yml
- name: Trigger Coolify Deployment
  run: |
    curl -X GET "${{ secrets.COOLIFY_WEBHOOK }}" \
      -H "Authorization: Bearer ${{ secrets.COOLIFY_TOKEN }}"

Problem 6. Builds Get Stuck or Fail Silently in Coolify

The deployment log shows activity, then freezes. Or the build is marked as failed, but there is no useful error message. Stuck builds are frustrating, but there is a clear way to debug them.

This Coolify troubleshooting guide recommends always enabling verbose logs first before anything else.

Step 1: Enable verbose build logs

By default, Coolify hides most build output. You can turn it on by going to Project → Configuration → Advanced, and add the environment variable:

BUILDKIT_PROGRESS=plain

Step 2: Check disk space

Running out of disk space is one of the most common hidden causes of stuck builds. Coolify accumulates Docker images and build caches over time:

df -h
docker system df

If the disk is full, clean up:

docker system prune -a --volumes -f

You can set up a weekly cleanup cron job to prevent this from coming back:

# Add to root's crontab (crontab -e)
0 3 * * 0 docker system prune -a --volumes -f --filter "until=168h" >> /var/log/coolify-cleanup.log 2>&1

Step 3: Check for port mismatches

If the build completes but the container is immediately marked unhealthy, the port your app listens on probably does not match what Coolify expects. Check Configuration → Ports in Coolify and make sure the port in your app code or Dockerfile matches.

# Use an environment variable for the port instead of hardcoding it
const PORT = process.env.PORT || 3000;

Step 4: Health check timeouts

If your app takes more than 30 seconds to start, which is common with Next.js apps or apps that run heavy migrations, Coolify marks the deployment as failed. Increase the health check timeout:

# Add to your environment variables in Coolify
HEALTHCHECK_INTERVAL=10
HEALTHCHECK_TIMEOUT=120
HEALTHCHECK_RETRIES=5

Or in your Dockerfile:

HEALTHCHECK --interval=10s --timeout=30s --start-period=120s --retries=3 \
  CMD curl -f http://localhost:${PORT}/health || exit 1

Step 5: View container logs directly

If the Coolify UI logs are not helpful, check Docker logs directly on the server:

# List running containers
docker ps

# View logs for a specific container (replace with your actual container name)
docker logs your-app-container --tail 100 -f

Step 6: Container name conflict

If a deployment fails with “container name already in use“, a leftover helper container is blocking the new one:

# Find and remove stuck containers
docker ps -a | grep your-app-name
docker rm -f CONTAINER_ID

Problem 7. Coolify Dashboard Shows Unhealthy After Server Reboot

You restarted your server, and now the Coolify dashboard itself is not loading or shows an unhealthy status, even though your deployed apps are still running fine.

This is a known issue where the coolify-redis data can get into a bad state after a hard reboot. The fix:

# Stop Docker completely
sudo systemctl stop docker.socket
sudo systemctl stop docker

# Clear the Redis data
sudo rm -f /var/lib/docker/volumes/coolify-redis/_data/*

# Reboot
sudo shutdown -r now

After reboot, run docker ps to confirm all Coolify containers are healthy. In some cases, just restarting Docker is enough:

sudo systemctl restart docker
docker ps --format "table {{.Names}}\t{{.Status}}"

Problem 8. No Available Server (503 Error) on Deployed App

Your deployment says it succeeded, but when you visit the domain, you get a 503 No Available Server or Bad Gateway error. This almost always means Traefik cannot reach your container. Use this checklist:

1. Check if the container is running:

docker ps | grep your-app

2. Check port config: in Coolify, make sure the container port matches the port your app actually listens on.

3. Check domain config: make sure the domain in Coolify includes https:// and does not have a trailing slash.

4. Check Traefik labels: view proxy logs:

docker logs coolify-proxy --tail 100

5. Restart the proxy: go to Coolify Dashboard → Your Server → Restart Proxy.

Quick Checklist for Coolify Troubleshooting Guide

You can use this when a deployment breaks and you are not sure where to start. Go through it in order:

• df -h: Is disk space above 85%?
• docker ps: Are all Coolify containers healthy?
• docker logs coolify --tail 50: any errors in the Coolify container itself?
• Enable BUILDKIT_PROGRESS=plain to see the full build output.
• Check the deployment logs in the Coolify UI.
• docker logs your-app-container --tail 100: What does the app say?
• dig yourdomain.com @8.8.8.8 +short: Does DNS resolve to the right IP?
• docker logs coolify-proxy --tail 100: Any SSL or routing errors?
• Check GitHub webhook delivery history for failed payloads.
• Check cloud provider firewall: are ports 80, 443, and 22 open?

Installing Coolify the Right Way: Prevent Problems Before They Start

Most of the problems in this guide can be avoided by starting with a clean server and following the correct installation steps. If you have not installed Coolify yet or want to start fresh, this tutorial provides the full process on Ubuntu: How to Install Coolify on Ubuntu VPS. It covers pre-install checks, firewall setup, DNS configuration, and first-run settings, all the things that prevent issues before they happen.

If your current VPS is already messy, including old Docker versions, conflicting packages, and low memory, the smartest move is to use a fresh Linux VPS and start clean. Coolify installs in under 5 minutes on a fresh Ubuntu 22.04 LTS server.

Conclusion

Most Coolify problems fall into a small set of categories:

• Docker is not installing correctly.
• DNS records are pointing to the wrong place.
• SSL permissions are off.
• Webhook secrets not matching.
• Builds timing out because of disk or memory issues.

This Coolify troubleshooting guide helps you spend less time guessing and more time fixing. Start with the quick checklist above, follow the symptom that matches your situation, and run the commands to verify each layer.

FAQs