Proxy Request Error: Causes and Step-by-Step Fix

What the ECONNREFUSED Error Means

The error message typically looks like: [HPM] Error occurred while trying to proxy request: /api/data or Error occurred while trying to proxy request to http://localhost:3000. It means your proxy server (often webpack-dev-server, Vite, Nginx, or an API gateway) attempted to forward a request to the target backend, but the operating system rejected the connection attempt. The proxy does not receive an HTTP response because the connection was never established at the network level. This halts development, as the frontend cannot fetch data from the API, and requires immediate configuration of routing or verification of network services.

Common Causes

1. The target server (Node.js, Python, Go microservice) is not running or has crashed.
2. An incorrect port, IP address, or typo is specified in the target configuration file.
3. A local firewall or antivirus is blocking outbound connections to non-standard ports.
4. Protocol mismatch: the proxy tries to connect via https, but the target server only listens on http (or lacks a properly configured self-signed certificate).
5. Routing issues in Docker networks: containers are in different virtual networks and cannot resolve each other by service name.

Solutions

Method 1: Verify Target Server Availability

First, ensure the service you are proxying requests to is actually running and accessible.

1. Open a terminal and run:

curl -v http://localhost:<YOUR_PORT>/

2. If the response shows Connection refused, the process is not running or is listening on a different interface (e.g., only IPv6).
3. Restart the backend and check its logs for startup errors.

💡 Tip: Use netstat -tuln or lsof -i :<port> to see exactly which address and port your process is listening on.

Method 2: Adjust Proxy Configuration

If the server is running but the error persists, check the routing settings in your development tool or web server.

For Webpack Dev Server / Create React App:

// webpack.config.js or devServer config file
module.exports = {
  devServer: {
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,              // Replaces the Host header in the request
        secure: false,                   // Disables SSL verification for local development
        logLevel: 'debug'                // Enables detailed console output
      }
    }
  }
};

⚠️ Important: The changeOrigin: true parameter is mandatory if the target server validates the Host header. Without it, many frameworks will drop the connection for security reasons.

Method 3: Configure Docker Networks and Aliases

If you are developing within containers, localhost inside one container does not point to the host machine or other containers.

1. Ensure both services are on the same network in docker-compose.yml:

services:
  frontend:
    environment:
      - PROXY_TARGET=http://backend:3000
    networks:
      - app_net
  backend:
    networks:
      - app_net
networks:
  app_net:
    driver: bridge

2. In your proxy configuration, replace localhost with the service name (backend). Docker DNS will automatically resolve it to the internal IP.
3. Rebuild and restart the stacks with docker compose up -d --build.

Method 4: Disable Firewall or Add Rules

On some operating systems, inbound/outbound connections on non-standard ports are blocked by default security policies.

1. Open your operating system's firewall settings.
2. Add an allow rule for the backend port (e.g., TCP 3000).
3. If using ufw on Linux, run:

sudo ufw allow 3000/tcp
sudo ufw reload

4. Restart the proxy server and test the connection. For Windows Defender Firewall, use PowerShell: New-NetFirewallRule -DisplayName "Allow Backend Proxy" -Direction Inbound -LocalPort 3000 -Protocol TCP -Action Allow.

Prevention

To avoid this issue recurring in the future, adopt a few simple practices in your workflow. Always use environment variables (.env) to store proxy addresses instead of hardcoding URLs in configuration files. This allows you to quickly change endpoints when deploying to different servers without risk of typos. Set up automatic proxy restarts on config changes using nodemon or built-in watch modes. Regularly update packages like http-proxy-middleware and similar tools, as new versions fix issues with Keep-Alive handling, WebSocket connections, and timeouts.