How to Fix Coolify Bad Gateway Error

If you’re seeing a “Bad Gateway” error when trying to access your Coolify-deployed application through your domain, you’re not alone. This is one of the most common issues developers face with Coolify, but the good news is that it’s usually fixable within minutes once you understand what’s causing it.

Here’s the deal: your app might be running perfectly fine when you check it via your server’s IP address and port, but the moment you try to access it through your domain, you hit that frustrating 502 Bad Gateway error. Let’s fix that.

Understanding the Bad Gateway Error in Coolify

Before we jump into solutions, let’s quickly understand what’s happening. When you see a Bad Gateway error in Coolify, it means the Traefik proxy (Coolify’s default reverse proxy) is trying to reach your application but can’t establish a connection. Your container might be running, your app might be working internally, but something is blocking the proxy from routing traffic properly.

The most common culprits are port configuration issues, incorrect network settings, or your application listening on the wrong network interface. Let’s tackle each one.

The Difference Between Applications and Services in Coolify

This matters for troubleshooting, so let’s clarify:

Applications are deployed from Git repositories or other deployment methods (except one-click services). You’ll see a “Port Exposes” field in the dashboard for these.

Services are deployed using Docker Compose files or Coolify’s one-click service options. These use different network configurations and you might not see the same Network section in your UI.

Keep this distinction in mind as we go through the fixes because the configuration locations differ slightly.

Common Symptoms You’ll Notice

• Your app works when accessed via http://YOUR_SERVER_IP:PORT but fails on your domain
• You get a “No Available Server” error message
• The container shows as “Running” in Docker but the domain returns 502
• Health checks pass but actual requests fail
• Your logs show the app started successfully but it’s still unreachable

The Root Causes (And How to Diagnose Them)

1. Port Configuration Problems

This is the number one cause of bad gateway errors. Your application is listening on one port inside the container, but Coolify doesn’t know about it.

For Applications: Check the “Port Exposes” field in your Coolify dashboard. This needs to match the exact port your application is listening on inside the container.

For example, if your Node.js app is running on port 3000, that’s what should be in the Port Exposes field. If your FastAPI app uses 8000, enter 8000. Simple as that.

For Services: Look at your Docker Compose file. Make sure the ports are properly configured in your compose setup and align with how Coolify’s proxy expects to route traffic.

2. The Localhost vs 0.0.0.0 Problem

Here’s something that catches a lot of developers off guard: if your application is only listening on localhost or 127.0.0.1 inside the container, nothing outside that container can reach it. Not Traefik, not the proxy, not anything.

This is because of how Docker networking works. Each container has its own isolated network namespace. When you bind to localhost inside a container, you’re literally only accepting connections from within that same container.

The fix: Configure your application to listen on 0.0.0.0 instead. This tells your app to accept connections from all network interfaces, which allows the Traefik proxy to connect to it.

Here’s how to do this for different frameworks:

Node.js/Express:

app.listen(3000, '0.0.0.0', () => {
  console.log('Server running on 0.0.0.0:3000');
});

FastAPI/Python:

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

Flask:

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

Laravel/PHP: In your .env file or server configuration, make sure PHP-FPM or your web server is configured to accept connections from the Docker network, not just localhost.

3. Host Port Mapping Conflicts

If you’ve added port mappings in your Docker Compose file (like "8888:80"), this can interfere with how Coolify’s proxy routes traffic.

When you manually map a port to the host, you’re bypassing Coolify’s internal routing mechanism. The proxy expects to connect to your container through Docker’s internal network, but the port mapping makes it accessible directly on the host instead.

The solution: Remove the port mappings from your compose file and let Coolify handle the routing. The proxy will automatically route traffic to the correct container port.

Before (causes issues):

services:
  app:
    image: nginx:latest
    ports:
      - "8888:80"  # Remove this

After (works correctly):

services:
  app:
    image: nginx:latest
    # No ports mapping - let Coolify/Traefik handle routing

4. Container Health and Status Issues

Sometimes the bad gateway happens because the container itself is having problems.

What to check:

• Is the container stuck at “Starting” status?
• Is the health check failing?
• Did the container crash after starting?

Check your application logs in Coolify. Look for error messages during startup. Common issues include:

• Missing environment variables
• Database connection failures
• Permission problems with files or directories
• Dependency installation failures

If the health check is causing problems and you’ve verified your app is actually running, you might need to adjust or temporarily disable the health check to get things working.

5. Storage and Resource Limitations

This one is sneaky. If your server runs out of disk space, memory, or other resources, Coolify itself can start throwing Bad Gateway errors, including on its own dashboard.

Check your server resources:

df -h  # Check disk space
free -h  # Check memory
docker system df  # Check Docker disk usage

If you’re running low on space, clean up unused Docker resources:

docker system prune -a --volumes

Just be careful with this command as it removes stopped containers, unused networks, and dangling images.

Step-by-Step Fix Guide

Let’s walk through fixing this systematically:

Step 1: Verify Your Port Configuration

1. SSH into your container or check your application code
2. Find what port your app is listening on
3. In Coolify’s dashboard, go to your application’s settings
4. Update the “Port Exposes” field with the correct port number
5. Save and redeploy

Step 2: Check the Listening Address

1. Look at your application’s startup code
2. Make sure it’s binding to 0.0.0.0, not localhost or 127.0.0.1
3. Update your code if needed
4. Commit and redeploy

Step 3: Remove Host Port Mappings

1. Open your Docker Compose file (if using one)
2. Remove any ports: sections that map to the host
3. Let Coolify handle the routing through Traefik
4. Redeploy your service

Step 4: Add the Port to Your Domain URL

If you’re using a non-standard port, you might need to include it in your domain configuration in Coolify.

For example, if your app listens on port 8000, configure your domain as:

• https://yourdomain.com:8000

Coolify will handle routing external traffic from port 80/443 to your app’s internal port 8000.

Step 5: Check Container Logs and Health

1. View your application logs in Coolify
2. Look for startup errors or connection issues
3. Check the container status in the dashboard
4. If health checks are failing, review the health check command

Step 6: Test the Container Internally

Before dealing with proxy issues, verify your app works inside the container:

docker exec -it YOUR_CONTAINER_NAME curl http://localhost:YOUR_PORT

If this works, the problem is definitely with the proxy routing. If this fails, your app itself has issues.

Step 7: Inspect Traefik Proxy Logs

Check what Traefik is seeing:

docker logs -f coolify-proxy

Look for connection refused errors, timeout messages, or routing issues. These logs will often tell you exactly what’s wrong.

Advanced Troubleshooting

Network Isolation Issues

If you’ve defined custom Docker networks in your compose file, this can cause problems. Coolify’s proxy runs in its own network, and your app runs in your custom network. They can’t talk to each other.

Solution: Let Coolify manage networks automatically. Remove custom network definitions and use Coolify’s destination configuration instead.

Multiple Services Sharing Resources

If you’re running multiple applications and they’re conflicting over ports or resources, you’ll see intermittent bad gateway errors.

Make sure each application uses unique ports and that no two services are trying to bind to the same port on the host.

DNS and SSL Certificate Problems

Sometimes what looks like a bad gateway is actually a DNS or SSL issue.

Verify:

• Your domain’s DNS records point to your server’s IP
• SSL certificates are properly generated (check Traefik dashboard)
• You’re not mixing HTTP and HTTPS incorrectly

Checking Traefik Configuration

You can view Traefik’s dynamic configuration through the dashboard:

1. Go to Server settings in Coolify
2. Navigate to Proxy tab
3. Check Dynamic Configurations

Look for routing rules that match your application. Make sure the service backend points to the correct container and port.

Real-World Examples

Example 1: Node.js App with Wrong Binding

Problem: FastAPI app shows “Running” but domain returns Bad Gateway.

Diagnosis: App was binding to localhost only.

Fix:

# Before
uvicorn.run(app, host="127.0.0.1", port=8000)

# After  
uvicorn.run(app, host="0.0.0.0", port=8000)

Result: App immediately accessible through domain.

Example 2: Laravel with Port Mapping

Problem: Laravel app accessible on server IP with port but Bad Gateway on domain.

Diagnosis: Docker Compose had port mapping that bypassed Coolify’s proxy.

Fix: Removed ports: - "8000:80" from compose file, let Traefik handle routing.

Result: Domain worked perfectly after redeployment.

Example 3: Wrong Port Configuration

Problem: Nginx service showing Bad Gateway.

Diagnosis: Coolify was configured for port 80, but the custom Nginx config was listening on 8080.

Fix: Updated Port Exposes field from 80 to 8080.

Result: Instant fix, no redeployment needed.

Prevention Tips

Once you’ve fixed your bad gateway error, here’s how to avoid it in the future:

1. Always Configure Listen Address First

When starting a new project, immediately set your application to listen on 0.0.0.0. Make this a standard practice.

2. Document Your Ports

Keep a note of which port each application uses. This makes configuration much faster.

3. Test Locally with Docker First

Before deploying to Coolify, test your Docker setup locally. Make sure your app is accessible from outside the container.

4. Use Environment Variables for Configuration

Instead of hardcoding ports and hosts, use environment variables:

const PORT = process.env.PORT || 3000;
const HOST = process.env.HOST || '0.0.0.0';
app.listen(PORT, HOST);

5. Check Health Check Commands

Make sure your health check commands work reliably. A failing health check can cause Coolify to mark your app as unavailable even when it’s running.

6. Monitor Resource Usage

Keep an eye on disk space, memory, and CPU. Set up alerts if possible.

When to Ask for Help

If you’ve tried everything above and still have issues, it’s time to reach out for support. But before you do, gather this information:

• Your application logs from Coolify
• Coolify proxy logs (docker logs coolify-proxy)
• Screenshots of your configuration (port settings, domain config, etc.)
• A description of what you’ve already tried
• Your Docker Compose file (if using one)

The Coolify community is active and helpful. Join their Discord server and share this information in the support channel.

Frequently Asked Questions

Q: Why does my app work with IP:port but not with the domain?

This is the classic bad gateway scenario. It means your app is running and accessible directly, but Traefik can’t route to it. Check your port configuration in Coolify and make sure your app is listening on 0.0.0.0, not localhost.

Q: Do I need to expose ports in my Docker Compose file for Coolify?

No, and you probably shouldn’t. Coolify and Traefik handle routing internally. Exposing ports with host mappings can actually cause conflicts. Let Coolify manage the routing.

Q: My application logs show it’s running on 0.0.0.0:8000 but I still get Bad Gateway. What’s wrong?

Check two things: First, is the Port Exposes field in Coolify set to 8000? Second, are there any health checks failing? Look at the container status in Coolify’s dashboard.

Q: Can I use a custom port for my application?

Yes, absolutely. Just make sure the Port Exposes field in Coolify matches your app’s port. If you need to access it on a specific external port, include that in your domain configuration (like yourdomain.com:8000).

Q: What’s the difference between localhost and 0.0.0.0?

Localhost (127.0.0.1) only accepts connections from the same machine. In Docker, that means only from within the same container. 0.0.0.0 accepts connections from any network interface, allowing Traefik to connect from outside the container.

Q: How do I check if my app is actually listening on the correct port?

SSH into the container and run: netstat -tulnp or ss -tulnp. You’ll see what ports are open and what’s listening. Or use: docker exec YOUR_CONTAINER curl localhost:YOUR_PORT

Q: Why does my app work in development but not in Coolify?

Usually because of how you’re running the development server. Many dev servers default to localhost only. Make sure your production configuration explicitly sets the host to 0.0.0.0.

Q: Will removing port mappings break my application?

No, Traefik will still route traffic to your application through Docker’s internal networking. Your app remains accessible through the domain, but not through direct host port access.

Q: How long does it take for fixes to take effect?

Port configuration changes are usually instant (sometimes requiring a restart). Code changes that modify the listening address require a full redeployment. DNS changes can take minutes to hours to propagate.

Q: Can resource limitations cause Bad Gateway errors?

Yes. If your server runs out of disk space or memory, containers can fail to start or crash intermittently, causing bad gateway errors. Always monitor your server resources.

Conclusion

Bad Gateway errors in Coolify are frustrating, but they’re almost always caused by a handful of common configuration issues. In most cases, the fix is simple: ensure your app listens on 0.0.0.0, verify your port configuration matches what your app actually uses, and remove any manual port mappings that interfere with Traefik’s routing.

The key is systematic troubleshooting. Start with the basics (ports and listening addresses), check your logs for clues, and work your way through the checklist above. Most bad gateway issues resolve within minutes once you identify the root cause.

Remember that Coolify is designed to make deployment easier, and once you understand how its proxy system works, you’ll be able to diagnose and fix these issues quickly. The Docker networking layer, while powerful, can be counterintuitive at first, especially the localhost vs 0.0.0.0 distinction.

Keep experimenting, check those logs, and don’t hesitate to reach out to the Coolify community when you’re stuck. Happy deploying!