# Axios proxy setup: routing, auth and NO_PROXY

Source: https://ipvolt.com/guides/axios-proxy-setup
Markdown: https://ipvolt.com/guides/axios-proxy-setup.md

[Home](https://ipvolt.com/index.md) / [Guides](https://ipvolt.com/guides.md) / [Axios proxy setup: routing, auth and NO_PROXY](https://ipvolt.com/guides/axios-proxy-setup.md)

Category: Integration
Reviewed: 2026-09-28
Published: 2026-09-28
Reading time: 8 minutes
Author: ipvolt

Configure Axios proxies in Node.js, separate explicit settings from environment and agent routing, and reproduce authentication and TLS checks.

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](https://axios.rest/pages/advanced/request-config) and the [pinned HTTP adapter](https://github.com/axios/axios/blob/v1.20.0/lib/adapters/http.js).

## Run one explicit proxy check

Use [proxy-check.mjs](https://ipvolt.com/downloads/axios-proxy-setup/proxy-check.mjs), [package.json](https://ipvolt.com/downloads/axios-proxy-setup/package.json) and the [lockfile](https://ipvolt.com/downloads/axios-proxy-setup/package-lock.json) together. In a new directory, with Node 24.20.0 or later in the Node 24 line:

```sh
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:

```js
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](https://www.ipify.org/) 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](https://ipvolt.com/downloads/axios-proxy-setup/results.json) retain those observations.

| Configuration | Observed route | What to check |
| --- | --- | --- |
| HTTP adapter, explicit `proxy`, conflicting environment and `NO_PROXY` | Explicit proxy | Start here for a reproducible baseline. |
| HTTP adapter, no explicit proxy, matching `HTTP_PROXY` or `HTTPS_PROXY` | Environment proxy | Inspect the process environment as well as application code. |
| Environment-selected proxy, matching `NO_PROXY` entry | Direct | Success alone does not prove proxy use. |
| `proxy: false`, ordinary agent | Direct | Axios environment selection is disabled in this case. |
| Ordinary custom `http.Agent`, no explicit proxy | Axios environment proxy | Supplying an agent does not automatically remove Axios's environment handling. |
| Custom `http.Agent({ proxyEnv: ... })`, plus `proxy: false` | Agent's proxy | The agent still controls routing. |
| Fetch adapter, Axios `proxy` object | Direct | HTTP-adapter options do not configure this adapter. |

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](/guides/proxy-environment-variables) explains inheritance. The existing [NO_PROXY matrix](/blog/no-proxy-matching-tested) 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](https://nodejs.org/download/release/v24.20.0/docs/api/http.html#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](/guides/nodejs-fetch-proxy). 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.

| Observation | Next check |
| --- | --- |
| Proxy receives nothing, destination succeeds | Explicit versus inherited settings, `NO_PROXY`, selected adapter and agent ownership. |
| Proxy rejects authentication | Gateway, authentication method and account scope; follow the [407 guide](/guides/fix-proxy-error-407). |
| CONNECT succeeds, then certificate verification fails | Origin trust chain and hostname; keep TLS verification enabled. |
| Request reaches a stalled origin and times out | Request deadline and origin behaviour; a longer timeout does not establish the cause. |
| HTTP 200 with an unexpected body | Validate the response shape before accepting the check. |

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](https://ipvolt.com/downloads/axios-proxy-setup/lab.mjs) alongside the checker and pinned package files, then run:

```sh
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](https://ipvolt.com/downloads/axios-proxy-setup/README.md) 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](/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.](https://ipvolt.com/#waitlist-hero) One email when access opens. Nothing else.


## Sources & further reading

- [Axios: request configuration](https://axios.rest/pages/advanced/request-config)
- [Axios 1.20.0: HTTP adapter source](https://github.com/axios/axios/blob/v1.20.0/lib/adapters/http.js)
- [Node.js 24.20.0: built-in proxy support](https://nodejs.org/download/release/v24.20.0/docs/api/http.html#built-in-proxy-support)
- [ipify: public IP address API](https://www.ipify.org/)

## Related guides

- [Use a proxy with Node.js fetch](https://ipvolt.com/guides/nodejs-fetch-proxy.md)
- [Fix Node.js TypeError: fetch failed behind a proxy](https://ipvolt.com/guides/fix-node-fetch-failed-proxy.md)
- [Proxy environment variables: HTTP_PROXY and NO_PROXY](https://ipvolt.com/guides/proxy-environment-variables.md)
- [Fix proxy error 407 without guessing](https://ipvolt.com/guides/fix-proxy-error-407.md)

## About ipvolt

Examples use generic proxy settings, with links to the original technical documentation. Product-specific behavior must be checked with your provider. ipvolt is still in development.

## Know when access opens.

ipvolt · In development

We’re building proxy infrastructure for developers and data teams. Join the interest list for a heads-up when ipvolt is ready.

Consent: One email when access opens. Nothing else.

[Get early access](https://ipvolt.com/guides/axios-proxy-setup#waitlist-closing). Use the email form on this page to join the interest list.

[Privacy](https://ipvolt.com/privacy)