Axios proxy setup: routing, auth and NO_PROXY

For Axios in Node.js, start with the HTTP adapter and an explicit proxy object. Keep proxy credentials in proxy.auth, verify the route, and only then add environment variables or custom agents. Those layers can change the connection: in our local test, proxy: false still used a proxy when a custom Node agent had proxyEnv configured.

This guide uses Axios 1.20.0 and Node.js 24.20.0. Its 15 routing cases and four recipe checks are synthetic loopback tests, not measurements of an external proxy service. Browser Axios and the Axios fetch adapter are different paths; the proxy option belongs to Node's HTTP adapter. See Axios configuration and the pinned HTTP adapter.

Run one explicit proxy check

Use proxy-check.mjs, package.json and the lockfile together. In a new directory, with Node 24.20.0 or later in the Node 24 line:

for file in package.json package-lock.json proxy-check.mjs; do
  curl --fail --silent --show-error \
    "https://ipvolt.com/downloads/axios-proxy-setup/$file" -o "$file" || exit 1
done
npm ci --ignore-scripts --no-audit --no-fund

Have your secret manager supply PROXY_HOST, PROXY_PORT, PROXY_USER and PROXY_PASSWORD, then run node proxy-check.mjs. PROXY_HOST is a hostname without a scheme or credentials. PROXY_PROTOCOL defaults to http; use https only for a provider-documented TLS proxy endpoint. It describes the connection to the proxy, not the destination. Do not put real passwords into shell history or a coding-agent prompt.

The checker builds this configuration using separate credential fields:

const proxy = {
  protocol: process.env.PROXY_PROTOCOL || 'http',
  host: process.env.PROXY_HOST,
  port: Number(process.env.PROXY_PORT),
  auth: {
    username: process.env.PROXY_USER,
    password: process.env.PROXY_PASSWORD,
  },
};

This excerpt shows the shape; the downloadable script validates its inputs and performs the request. It selects adapter: 'http', disables redirects, caps the response at 4 KiB, and has a 5-second Axios timeout plus a 6-second abort signal. It checks that the returned JSON contains a valid IP address and prints only the result, status and an IP or error code. It does not print Axios's raw error or request configuration, which can contain credentials.

Running the script sends a request through your proxy to the third-party ipify IPv4 JSON endpoint by default. That service observes the request's public source address. Set a credential-free HTTPS CHECK_URL for an approved endpoint returning the same { "ip": "..." } shape. An observed IP is one route check; it does not verify a country, carrier, residential classification or performance guarantee. We tested the checker with controlled local responses, not public ipify.

Basic credentials sent to an ordinary HTTP proxy are not encrypted on the client-to-proxy connection merely because the destination is HTTPS. Use a TLS proxy endpoint when supported and keep certificate verification enabled. The lab tests an HTTP proxy tunnelling to a trusted HTTPS origin; it does not test TLS transport to the proxy itself.

Choose which layer owns routing

These observations use the pinned fixture with native environment-proxy startup flags disabled. “Direct” means the fixture proxy received nothing; “proxied” means it recorded a request or CONNECT. The raw results retain those observations.

For environment-driven routing, HTTP_PROXY applies to an HTTP destination and HTTPS_PROXY to an HTTPS destination. The value's scheme still describes the proxy: HTTPS_PROXY=http://gateway:port can select an HTTP proxy for an HTTPS destination. The environment variables guide explains inheritance. The existing NO_PROXY matrix covers its own named clients and versions, not this Axios experiment.

The native agent row is the exception to a blanket reading of “false disables proxies.” Node's built-in proxy support can give an agent its own routing configuration. In the fixture, proxy: false plus that agent still used its proxy; replacing it with a plain agent made the control request direct. We did not test every startup flag or third-party agent. Inspect the agent supplied to your process rather than treating an Axios setting as a network-wide guarantee.

For native Node fetch, use the Undici dispatcher guide. An Axios proxy object and a fetch dispatcher are different interfaces.

HTTPS and authentication: find the failing layer

Axios 1.20.0's HTTP adapter established a CONNECT tunnel for the lab's HTTPS destination. A trusted local CA allowed the request through; removing that trust produced DEPTH_ZERO_SELF_SIGNED_CERT. The proxy saw CONNECT but the HTTPS origin received no application request in the rejected-certificate case. Advice that Axios always needs a separate tunnelling package does not describe this tested version.

Use proxy.auth for proxy credentials; top-level Axios auth is destination authentication. In the successful CONNECT case, the fixture origin received no Proxy-Authorization header. The proxy received that credential at the tunnel step. This is scoped to the tested configuration, not arbitrary intercepting proxies or redirects.

Wrong credentials produced status 407 and code ERR_BAD_REQUEST for both the plain HTTP case and the checker’s HTTPS CONNECT case. The rejected CONNECT reached the proxy but produced no origin request. A raw Axios error can include its credential-bearing configuration: retain a sanitized code and available status instead of logging the whole object.

The stalled HTTP origin produced ECONNABORTED with a 100 ms fixture timeout. That establishes a local failure branch, not a useful production timeout or latency benchmark. The reusable checker uses larger bounded deadlines and never retries automatically.

Reproduce the routing matrix

Download lab.mjs alongside the checker and pinned package files, then run:

curl --fail --silent --show-error \
  https://ipvolt.com/downloads/axios-proxy-setup/lab.mjs -o lab.mjs
node lab.mjs local-results.json

The README documents prerequisites and cases. The fixture needs OpenSSL, binds random IPv4 loopback ports, generates a temporary local certificate, and uses invented credentials. Unset native environment-proxy startup flags first; the harness rejects those flags because they alter its baseline. Dependency installation contacts the package registry; fixture requests stay on loopback.

Recorded on 28 September 2026 with Node 24.20.0, Axios 1.20.0 and macOS arm64: 15 routing cases and four recipe checks passed. The checks cover routing, authentication, trusted and untrusted local HTTPS, adapter scope, timeout, valid IP output and unexpected-body rejection. They do not measure provider inventory, anonymity, geography or throughput, and do not test SOCKS, browser Axios, redirects or TLS transport to the proxy. Rerun the fixture after changing Axios, Node, an adapter or an agent.

For optional diagnostic help inside a coding agent, Proxy Toolkit MCP accepts sanitized error descriptions. Keep credentials and private URLs out of its arguments and verify suggested changes with a bounded request.

ipvolt proxy access is not open yet. Know when access opens. One email when access opens. Nothing else.