n8n proxy configuration error – HTTP_PROXY, HTTPS_PROXY, and NO_PROXY fix

The Complete Debug Guide – Corporate Firewalls, Docker, npm, Kubernetes, and the Silent Node-Level Bypass Nobody Else Covers

# Proxy is set ✓
$ docker exec n8n printenv | grep -i proxy
HTTP_PROXY=http://proxy.corp.com:8080
HTTPS_PROXY=http://proxy.corp.com:8080

# curl works ✓
$ docker exec n8n curl -I https://api.github.com
HTTP/1.1 200 OK

# But n8n AI node fails ✗
Error: connect ECONNREFUSED api.openai.com:443

# Startup log shows:
[INFO] Installing global HTTP proxy agents
[WARN] LangChain nodes: proxy not applied

Most proxy guides for n8n tell you to set HTTP_PROXY and HTTPS_PROXY and restart. That works — until it doesn’t, and you have no idea why. The real picture is messier: n8n uses a package called proxy-from-env internally, which has its own variable precedence rules. Several node types bypass the global proxy agent entirely due to open bugs. Running behind a reverse proxy adds a completely separate variable set. This guide covers every failure mode with real log signatures, confirmed reproduction steps, and the exact fix for each.

Sound familiar?

You’ve set the vars. You’ve restarted the container. You’ve verified curl works from inside. But one specific workflow usually the one hitting OpenAI, Slack, or a package install – keeps throwing ENOTFOUND. The answer isn’t in your env vars. It’s in which node type is making the request, and whether n8n’s proxy agent even applies to it. That’s what this guide actually explains.

How n8n Actually Handles Proxy Variables – The Mental Model

Before debugging anything, you need to understand that n8n doesn’t have a single proxy mechanism. It has three separate networking layers that each need proxy awareness independently. Most guides treat it as one thing. That’s the root cause of the confusion.

The critical insight most devs miss: n8n uses the proxy-from-env npm package internally. This package gives lowercase variables (http_proxy) precedence over uppercase (HTTP_PROXY) when both are present. If your system image or shell profile sets lowercase proxy vars, they silently override your uppercase Docker env vars. This is in the official n8n deployment docs but almost never surfaces in troubleshooting threads.

1. Configuring Proxy for Docker-Based n8n

If you encounter any ssl certificate error n8n resolve them before continuing – TLS interception and proxy errors often appear together in corporate environments.

1.1 – Quick test with docker run

Use this for a one-off test. Replace the proxy URL with your actual corporate proxy address and port before running.

docker run -d \
  --name n8n \
  -p 5678:5678 \
  -e HTTP_PROXY="http://proxy.mycorp.com:8080" \
  -e HTTPS_PROXY="http://proxy.mycorp.com:8080" \
  -e NO_PROXY="localhost,127.0.0.1" \
  n8nio/n8n

1.2 – Persistent setup with docker-compose.yml

Store proxy values in a .env file and reference them in the compose file. Never hardcode credentials directly in the YAML — keep the YAML in version control, keep the .env out of it.

version: "3.8"
services:
  n8n:
    image: n8nio/n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=strongPassword
      # Proxy settings — pulled from .env file
      - HTTP_PROXY=${HTTP_PROXY}
      - HTTPS_PROXY=${HTTPS_PROXY}
      - NO_PROXY=${NO_PROXY}
    volumes:
      - ~/.n8n:/home/node/.n8n

Matching .env file (never commit this):

HTTP_PROXY=http://proxy.mycorp.com:8080
HTTPS_PROXY=http://proxy.mycorp.com:8080
NO_PROXY=localhost,127.0.0.1

1.3 – Verify the proxy is actually being used

Run both after every configuration change before testing workflows. The first confirms the vars exist inside the container. The second confirms the proxy path actually works.

# Confirm vars are inside the container
docker exec n8n printenv | grep -i proxy

# Confirm outbound connectivity through proxy
docker exec n8n curl -I https://api.github.com

200 OK means the proxy is correctly applied. CONNECT ECONNREFUSED means the proxy URL or port is wrong. Note: Docker does not process PAC files – you must provide a direct proxy URL with a hostname and port.

Error: getaddrinfo ENOTFOUND api.slack.com
    at GetAddrInfoReqWrap.onlookup (dns.js:66:17)

EEFA tip: If you set proxy vars on the host but forget to pass them into the container, Docker has no way to inherit them. The container’s network stack is isolated. Every environment variable your n8n process needs must be explicitly declared at runtime — not assumed to exist because the host has them.

2. Configuring Proxy for npm-Based n8n Installations

If you encounter any docker compose configuration error n8n resolve it before continuing with the proxy setup.

2.1 – Global npm proxy settings

Run these two commands on the machine where n8n is installed. Validate immediately after setting.

npm config set proxy http://proxy.mycorp.com:8080
npm config set https-proxy http://proxy.mycorp.com:8080

# Validate — both should return your proxy URL
npm config get proxy
npm config get https-proxy

2.2 – Project-specific .npmrc (recommended for CI/CD)

Scoping to the project prevents this from affecting other tools on the machine. Preferred for CI/CD pipelines where global config changes are undesirable.

proxy=http://proxy.mycorp.com:8080
https-proxy=http://proxy.mycorp.com:8080
# Only if corporate proxy intercepts TLS and CA import isn't possible yet
strict-ssl=false

EEFA warning: strict-ssl=false disables certificate validation for all npm operations globally — not just proxy connections. Use it only as a temporary diagnostic step. The correct production fix is importing the corporate CA (covered in Section 7).

2.3 – Installing n8n and handling timeouts

npm install -g n8n

# If install times out, extend the retry window
npm config set fetch-retry-maxtimeout 120000

EEFA tip: If npm install still fails after setting the proxy, test the proxy path directly: curl -x http://proxy.mycorp.com:8080 https://registry.npmjs.org/. A 200 response means npm’s proxy config is the problem, not the proxy itself. A connection error means you have the wrong proxy URL.

3. The Silent Proxy Bypass – Why Specific n8n Nodes Ignore HTTP_PROXY Entirely

This is the gap no other proxy guide covers. If your HTTP Request node works through the proxy but OpenAI, Gemini, RSS, or PGVector nodes still fail – you are not configuring the proxy incorrectly. You are hitting a known architectural limitation where the third-party libraries bundled into those specific nodes manage their own HTTP clients and bypass the global proxy-from-env agent that n8n installs at startup.

Most devs get stuck here for hours. The frustrating part: the HTTP Request node works perfectly on the same API endpoint that the AI node fails on. This is the exact symptom of the bypass bug, not a configuration error.

What to do for each bypass case?

For AI / Langchain nodes (OpenAI, Gemini): The only reliable workaround today is to configure direct internet access to the AI API endpoint at the network/firewall level, or use a transparent proxy that intercepts all outbound traffic rather than relying on application-level proxy injection. There is no env var fix for this specific case while the bug remains open.

For community package installs returning 502: Set npm proxy config directly inside the running container – this is separate from the container’s environment variables and persists as long as the container volume is preserved:

docker exec n8n npm config set proxy http://proxy.mycorp.com:8080
docker exec n8n npm config set https-proxy http://proxy.mycorp.com:8080

The case-sensitivity trap — set both forms: To avoid the proxy-from-env lowercase-precedence issue, declare both lowercase and uppercase in your Docker environment so there’s no conflict regardless of what the base image sets:

# In docker-compose.yml environment block — set both forms
- http_proxy=http://proxy.mycorp.com:8080
- HTTP_PROXY=http://proxy.mycorp.com:8080
- https_proxy=http://proxy.mycorp.com:8080
- HTTPS_PROXY=http://proxy.mycorp.com:8080
- no_proxy=localhost,127.0.0.1
- NO_PROXY=localhost,127.0.0.1

Error: connect ECONNREFUSED api.openai.com:443
[INFO] Installing global HTTP proxy agents
[WARN] LangChain nodes may not respect global proxy configuration

EEFA tip: The startup log line “Installing global HTTP proxy agents” confirms the proxy agent is loaded. If you don’t see this line when n8n starts, your proxy vars are not present when the n8n process launches – check that they’re set before startup, not injected after. If you see the line but specific nodes still fail, you’re in bypass territory.

Apply sections 1–3 first. Then check the node type.

If the proxy is correctly set and curl confirms it works, but a specific node still fails – you are not doing anything wrong. You’ve hit a known node-level bypass. The remaining sections cover the other failure modes: reverse proxy crash, Kubernetes, SOCKS5, and authenticated proxies.

4. The Reverse Proxy Startup Crash – N8N_TRUST_PROXY and N8N_PROXY_HOPS

This failure mode is entirely separate from outbound proxy configuration. It appears when n8n itself is running behind a reverse proxy (Nginx, Traefik, Caddy) and n8n’s internal Express server doesn’t trust the X-Forwarded-For headers being passed by that proxy. The container enters a crash loop immediately on startup, and the error message mentions “trust proxy setting” – which sounds like a network issue, not a startup crash. This causes a lot of confusion because the fix is two environment variables, not a network change.

Add both variables to your docker-compose.yml environment block alongside your existing configuration:

environment:
  - N8N_TRUST_PROXY=true    # Tells Express to trust X-Forwarded-For headers
  - N8N_PROXY_HOPS=1        # Number of reverse proxy hops in front of n8n
  - HTTP_PROXY=${HTTP_PROXY}
  - HTTPS_PROXY=${HTTPS_PROXY}
  - NO_PROXY=${NO_PROXY}

If you have more than one reverse proxy in the chain (e.g., a CDN in front of Nginx in front of n8n), set N8N_PROXY_HOPS to match the hop count. For most self-hosted setups, 1 is correct.

ValidationError: The 'X-Forwarded-For' header is set but the Express
'trust proxy' setting is false (default). This could indicate a
misconfiguration which would prevent express-rate-limit from accurately
identifying users.

EEFA tip: This error is identical regardless of which reverse proxy software you’re using – Nginx, Traefik, Caddy, or anything else. The fix is entirely inside n8n’s environment variables. You don’t need to change a single line of your Nginx config to resolve it.

5. Kubernetes Proxy Setup for n8n

Running n8n in Kubernetes behind a corporate proxy adds one additional concern that Docker Compose doesn’t have: credentials must not be stored as plaintext environment variables in the Deployment spec. Kubernetes Secrets handle this cleanly. Here is a complete working pattern.

Step 1 – Create a Secret for proxy credentials:

apiVersion: v1
kind: Secret
metadata:
  name: n8n-proxy-creds
type: Opaque
stringData:
  PROXY_USER: myuser
  PROXY_PASS: mypassword

Step 2 – Inject proxy and trust vars into the n8n Deployment:

env:
- name: HTTP_PROXY
  value: "http://proxy.corp.com:3128"
- name: HTTPS_PROXY
  value: "http://proxy.corp.com:3128"
- name: NO_PROXY
  value: "localhost,127.0.0.1,.svc.cluster.local"
- name: N8N_TRUST_PROXY
  value: "true"
- name: N8N_PROXY_HOPS
  value: "1"

EEFA tip: Always include your cluster’s internal service DNS suffix (e.g., .svc.cluster.local) in NO_PROXY. Without it, n8n’s calls to other services in the same cluster may route through the corporate proxy and fail – those addresses aren’t reachable externally.

6. When and How to Use NO_PROXY?

NO_PROXY tells Docker and Node.js to bypass the proxy for listed hosts. A misconfigured NO_PROXY is one of the most common reasons proxy configuration appears to stop working after initially working – someone adds a host to the exclusion list, and suddenly that external API becomes unreachable.

NO_PROXY=localhost,127.0.0.1,::1,*.mycorp.internal

Use NO_PROXY exclusively for internal services databases, internal APIs, other Docker containers, Kubernetes cluster services — that the proxy cannot or should not route. Do not list external API domains (e.g., api.slack.com) in NO_PROXY unless they are directly reachable without the proxy. Listing them there will cause those calls to fail silently in a restricted network.

7. SOCKS5 Proxy and ALL_PROXY – For Non-Corporate Setups

If you’re running n8n through a SOCKS5 proxy (common with self-hosted setups using xray-core, V2Ray, or similar tools), HTTP_PROXY alone won’t cover all outbound connections. Use ALL_PROXY instead — it applies to all outbound connections regardless of protocol, not just HTTP/S.

-e ALL_PROXY="socks5h://172.17.0.1:1080"
-e HTTP_PROXY="http://172.17.0.1:1080"
-e HTTPS_PROXY="http://172.17.0.1:1080"
-e NO_PROXY="localhost,127.0.0.1"

EEFA tip: Use socks5h:// (not socks5://) when the proxy should handle DNS. With socks5://, DNS lookups happen locally first – which defeats the purpose in restricted networks where local DNS won’t resolve external hostnames. The trailing h is not a typo.

8. Authenticated Proxies and Self-Signed Certificates

8.1 – Authenticated proxy URL syntax

Credentials go directly in the proxy URL. For production, use Docker secrets instead of plaintext env vars.

export HTTP_PROXY="http://user:password@proxy.mycorp.com:8080"
export HTTPS_PROXY="http://user:password@proxy.mycorp.com:8080"

Production-safe approach with Docker secrets:

secrets:
  proxy_user:
    file: ./secrets/proxy_user.txt
  proxy_pass:
    file: ./secrets/proxy_pass.txt

services:
  n8n:
    environment:
      - HTTP_PROXY=http://$(cat /run/secrets/proxy_user):$(cat /run/secrets/proxy_pass)@proxy.mycorp.com:8080

8.2 – Handling self-signed proxy certificates

When the corporate proxy performs TLS interception, it presents its own certificate. The container’s Node.js process doesn’t trust it by default. The correct fix is importing the corporate CA – not disabling SSL validation globally.

Get the CA cert from your IT team, then build a custom n8n image with it trusted:

FROM n8nio/n8n:latest
COPY corp-ca.crt /usr/local/share/ca-certificates/
RUN update-ca-certificates

Build and run the custom image:

docker build -t myorg/n8n-proxy .
docker run -d -p 5678:5678 myorg/n8n-proxy

Error: self signed certificate in certificate chain
    at TLSSocket.onConnectEnd (_tls_wrap.js:1495:19)
UNABLE_TO_VERIFY_LEAF_SIGNATURE

EEFA security tip: strict-ssl=false and NODE_TLS_REJECT_UNAUTHORIZED=0 both disable certificate validation globally — not just for the proxy connection. This means n8n will not validate TLS for any external service it calls, including all your workflow API calls. Acceptable for one-off debugging. Never in production.

Common Pitfalls: Full Symptom Reference

Every proxy failure in n8n is diagnosable.

Once you know which of the five failure modes you’re dealing with — Docker env vars, npm config, node-level bypass, reverse proxy crash, or case-sensitivity conflict — the fix is mechanical, not a guessing game. Use the decision tree below to find yours in under 2 minutes.

Your Debug Decision Tree – Find Your Failure Mode in 5 Steps

Run these steps in order. Each step eliminates one failure mode and tells you exactly where to look next.

Quick Reference: All Variables and What They Control

Frequently Asked Questions (FAQ)

Conclusion: n8n Proxy Errors Are Predictable Once You Know the Map

Proxy failures in n8n feel chaotic because they can originate from four different system layers – Docker runtime, n8n’s internal proxy agent, third-party node libraries, and npm’s own HTTP client – each of which requires a separate configuration approach. Once you understand the three-layer model and which node types bypass the global proxy agent, every failure becomes traceable to a specific, mechanical fix rather than a guessing game of restarting containers and rotating environment variables.

The debugging order matters: confirm the vars are inside the container first, then confirm the proxy is reachable via curl, then identify whether the failing component is one of the known node types that bypasses the proxy agent entirely. If n8n is crashing rather than failing to connect, the issue is almost certainly the reverse proxy headers — fixed with two environment variables in under a minute. Community package failures are a separate npm-level issue, fixed with a single command inside the container. None of this is random once you have the decision tree.

If TLS is causing additional failures after your proxy is configured, see the SSL certificate error in n8n guide. If your compose file structure is producing errors alongside proxy setup, see the docker-compose configuration error guide.