How to Fix n8n "ECONNREFUSED" Connection Error in Docker Compose

Running a self-hosted n8n instance via Docker Compose is one of the most cost-effective ways to manage your AI automation workflows. However, encountering an ECONNREFUSED or "Failed to connect to host" error during execution or initial startup can completely stall your automated pipelines.

This error typically occurs when the n8n container cannot communicate with external services, webhooks, or its own PostgreSQL database container due to mismatched port bindings or incorrect network configurations.

In this guide, you will learn the exact root causes of this error and how to fix it in 3 simple steps.

Prerequisites

Before proceeding with the fix, ensure you have:

SSH access to your VPS or local terminal access.
Basic familiarity with Docker Compose commands.
An active n8n instance running on Docker.

Step 1: Verify Your Docker Port Mapping

The most common cause of ECONNREFUSED is an improperly configured port binding in your docker-compose.yml file. By default, n8n listens on port 5678.

1. Open your docker-compose.yml file:

nano docker-compose.yml

2. Locate the n8n service block and check the ports section:

version: '3.8'

services:
  n8n:
    image: n8nio/n8n:latest
    restart: always
    ports:
      - "5678:5678"
    environment:
      - N8N_HOST=n8n.yourdomain.com
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - NODE_ENV=production
      - WEBHOOK_URL=https://n8n.yourdomain.com/

Important Note: Make sure the left side (host port) matches the right side (container port) unless you are intentionally routing traffic through a reverse proxy like NGINX or Traefik.

Step 2: Check Inter-Container Networking

If n8n is trying to connect to another local container (such as a PostgreSQL database or Redis cache) and throwing ECONNREFUSED, you cannot use localhost or 127.0.0.1 inside the n8n nodes.

Within Docker's internal network, localhost refers to the n8n container itself, not your host machine or other containers.

Incorrect Database Host: localhost or 127.0.0.1
Correct Database Host: Use the service name defined in your docker-compose.yml (e.g., postgres or db).

Example Fix for Postgres Connection:

# Incorrect:
DB_POSTGRESDB_HOST=127.0.0.1

# Correct (matching your Docker service name):
DB_POSTGRESDB_HOST=postgres

Step 3: Restart and Validate the Container

After saving your configuration changes, restart your Docker containers to apply the new network rules:

# Stop running containers
docker compose down

# Start containers in detached mode
docker compose up -d

# View real-time logs to confirm the fix
docker compose logs -f n8n

Look for the following log output to confirm that n8n is up and listening properly:

n8n ready on 0.0.0.0, port 5678
Editor is now accessible via https://n8n.yourdomain.com

Troubleshooting Checklist Summary

If you still face connectivity issues, verify these final checks:

Firewall Rules: Ensure UFW or your cloud provider's security group allows incoming/outgoing traffic on port 5678 or 443.
Reverse Proxy Config: If using NGINX, verify that proxy_pass http://127.0.0.1:5678; is active in your server block.
Webhook URL Mismatch: Ensure WEBHOOK_URL includes the trailing slash and correct protocol (https://).

PromtLogic