Axios Proxy Configuration in Node.js: HTTP, HTTPS and SOCKS5

Check which Axios adapter makes the request

Axios runs in both browsers and Node.js. Its request configuration reference marks the proxy option as Node-only. A React component that calls Axios in the browser cannot select an outbound HTTP proxy by adding the Node proxy object.

Place this integration in your server, job runner or backend route. Keep its credentials in that environment. A public browser bundle is not a secret store, and a server endpoint should authorize its callers before forwarding requests.

The example explicitly selects adapter: 'http'. If your project selects the Fetch adapter, uses a custom adapter, or wraps Axios inside another SDK, verify that runtime’s networking configuration separately. A successful request from a local Node script does not establish how a deployed worker or remote browser routes its traffic.

Use a version with the documented HTTPS behavior

We checked Axios 1.20.0 on October 11, 2026 using Node 22.23.1. Install the tested version in an isolated project, or review the release against your existing lockfile:

npm install axios@1.20.0

The released Node HTTP adapter creates a CONNECT tunnel for HTTPS targets when using the built-in HTTP(S) proxy configuration. Proxy authentication belongs on that CONNECT request; the destination TLS request travels inside the tunnel. This distinction matters when comparing an older workaround with the current implementation.

The proxy protocol describes the client’s connection to the proxy. An http proxy can tunnel a request to an https destination. An https proxy adds TLS to the client-to-proxy hop. Choose the protocol your endpoint actually supports; changing the string does not enable TLS on a plain HTTP proxy.

Run an authenticated route check

Set PROXY_SERVER, PROXY_USERNAME and PROXY_PASSWORD in your environment. The server value contains a scheme and hostname, with a port when needed: http://proxy.example:8080. Save this as check-proxy.cjs:

const axios = require('axios');
const { isIP } = require('node:net');

function proxyConfig(server, username, password) {
  const endpoint = new URL(server);
  if (!['http:', 'https:'].includes(endpoint.protocol) || endpoint.username ||
      endpoint.password || endpoint.pathname !== '/' || endpoint.search || endpoint.hash) {
    throw new Error('Use an HTTP(S) proxy URL without credentials or a path');
  }
  return {
    protocol: endpoint.protocol.slice(0, -1),
    host: endpoint.hostname,
    port: Number(endpoint.port || (endpoint.protocol === 'https:' ? 443 : 80)),
    auth: { username, password },
  };
}

async function checkExit(proxy, options = {}) {
  const response = await axios.get(options.target || 'https://api.ipify.org?format=json', {
    adapter: 'http',
    proxy,
    httpsAgent: options.httpsAgent,
    timeout: 10000,
    signal: AbortSignal.timeout(15000),
    maxRedirects: 0,
    maxContentLength: 65536,
    responseType: 'json',
    validateStatus: status => status === 200,
  });
  if (!isIP(response.data?.ip)) throw new Error('Expected a valid IP response');
  return response.data.ip;
}

if (require.main === module) {
  (async () => {
    const { PROXY_SERVER, PROXY_USERNAME, PROXY_PASSWORD } = process.env;
    if (!PROXY_SERVER || !PROXY_USERNAME || !PROXY_PASSWORD) {
      throw new Error('Missing proxy configuration');
    }
    console.log(await checkExit(proxyConfig(PROXY_SERVER, PROXY_USERNAME, PROXY_PASSWORD)));
  })().catch(error => {
    console.error('Proxy check failed', { code: error.code || error.name, status: error.response?.status });
    process.exitCode = 1;
  });
}
module.exports = { checkExit, proxyConfig };

Run node check-proxy.cjs. The default request goes to ipify. It returns the IP observed for that request, which the code validates before reporting success.

proxy.auth supplies credentials to the proxy. The top-level Axios auth setting instead controls Basic authentication to the destination. Preserve that distinction when adding an API token or application login.

The script rejects redirects so an IP diagnostic does not silently navigate elsewhere. It also limits the response body and reports only an error code and HTTP status. The optional httpsAgent argument exists for a controlled trust configuration, such as the local test certificate used in our fixture; ordinary public TLS uses the default certificate checks.

Make environment precedence explicit

The configuration reference supports proxy environment variables and exclusions through no_proxy. It also documents newer Node environments that delegate proxy behavior through agents with proxyEnv enabled. That means a process flag or custom agent can matter when no explicit proxy is supplied.

Use one deliberate configuration path for a job. The displayed example passes an explicit proxy object. When investigating inconsistent routes, record the adapter, endpoint identifier and relevant environment-variable names without logging their secret values.

For a custom proxy agent, follow its integration instructions and disable Axios’s separate proxy resolution with proxy: false. Do not assume this disables all behavior inside an independently configured agent. A worker started with Node’s environment-proxy flags may need its agent configuration reviewed too.

Use a SOCKS agent when the endpoint requires SOCKS5

Axios’s built-in proxy object is for HTTP(S) proxies. The maintained socks-proxy-agent package provides a Node HTTP agent for SOCKS connections. Install a compatible version; version 10.1.0 requires Node 20 or later.

const { SocksProxyAgent } = require('socks-proxy-agent');
const agent = new SocksProxyAgent(process.env.SOCKS_PROXY_URL);
try {
  const response = await axios.get('https://api.ipify.org?format=json', {
    adapter: 'http',
    httpAgent: agent,
    httpsAgent: agent,
    proxy: false,
    timeout: 10000,
    signal: AbortSignal.timeout(15000),
    maxRedirects: 0,
    maxContentLength: 65536,
  });
  if (response.status !== 200 || !isIP(response.data?.ip)) {
    throw new Error('Expected an IP response');
  }
  console.log(response.data.ip);
} finally {
  agent.destroy();
}

This is an alternative to the HTTP example, using its axios and isIP imports. Supply a SOCKS URL supported by the agent, such as socks5h://user:password@proxy.example:1080, with credentials URL-encoded when they contain reserved characters. The socks5h form requests proxy-side hostname resolution. Our executed fixtures covered the HTTP(S) example, not a commercial SOCKS service.

Keep timeouts, authentication errors and destination responses separate

Axios distinguishes a response with an unacceptable status from a request that received no response and from a configuration failure. Its error reference also explains why an Axios error may contain request configuration. Avoid dumping error.config, the full request or serialized errors into logs that can expose connection secrets.

A proxy 407 points to proxy authentication. A destination 401 usually needs destination credentials. A 403 or 429 needs inspection of the returned service response; it is not a reason to retry through an unbounded sequence of endpoints. Preserve a Retry-After instruction when the service supplies one.

The cancellation documentation recommends combining request timeouts with cancellation. Here the timeout is ten seconds and the abort signal is fifteen seconds. These bounds make a failed dependency visible to a worker instead of letting it wait indefinitely.

Test the route used by your worker

Our Axios 1.20.0 fixture checks passed for authenticated HTTP requests, an HTTPS CONNECT tunnel with a trusted local certificate, explicit proxy configuration despite conflicting environment variables, wrong-credential rejection and redirect rejection. The local TLS destination received neither proxy credentials nor an unintended origin Authorization header.

These are code-behavior checks. They do not measure provider latency or establish access to an external website. Repeat the route check from the deployed process, and test certificate trust without setting rejectUnauthorized: false.

For an AI workflow, locate the actual network caller. This Axios setting controls the HTTP calls made by this Node code; it does not automatically configure a browser tool, another SDK’s Fetch client or the model API connection. Keep those clients separately observable and use Playwright context routing when a browser makes the request.

Frequently asked questions