Axios Proxy Builder

Common errors

• AxiosError: Network Error

  cause This generic error often indicates that Axios could not establish a connection to the target server or the proxy. Common causes include an unreachable proxy server, incorrect proxy credentials (if embedded in URL via env vars), or network connectivity issues between your application and the proxy/target.
  fix 1. Verify your `HTTP_PROXY`/`HTTPS_PROXY` environment variables are correctly formatted and point to a running, accessible proxy server. 2. Check network connectivity (e.g., `ping` or `curl`) from your application's host to the proxy server. 3. Ensure any required proxy authentication (if supported via URL in env var) is correct.

• Error: Invalid proxy protocol: null

  cause This error typically occurs if the `HTTP_PROXY` or `HTTPS_PROXY` environment variable is malformed and does not contain a valid protocol (e.g., `http://` or `https://`). Axios expects the `protocol` property in the proxy configuration object to be 'http' or 'https'.
  fix Review your proxy environment variables. Ensure they start with a valid protocol, e.g., `export HTTP_PROXY="http://proxy.example.com:8080"`.

• ReferenceError: axios is not defined

  cause This package generates a proxy *object* for Axios, but it does not automatically install or import Axios itself. This error means Axios has not been imported or installed in your project.
  fix Install Axios (`npm install axios`) and ensure you import it in your code using `import axios from 'axios';` or `const axios = require('axios');`.

• 407 Proxy Authentication Required

  cause Your proxy server requires authentication (username and password) which was not provided or was incorrect. While `axios-proxy-builder` can parse credentials embedded in the proxy URL (e.g., `http://user:pass@host:port`), direct support for separate `auth` objects in the environment variables is not explicit.
  fix If your proxy requires authentication, include the username and password directly in the proxy environment variable URL (e.g., `http://user:pass@proxy.example.com:8080`). Ensure these credentials are correct.

Warnings

• gotcha The package is in early development (version 0.1.2) and its API may not be stable. Users should be aware that breaking changes could occur in future minor or patch versions before a 1.0 release.
  Fix: Monitor GitHub repository for updates and breaking changes before upgrading. Consider pinning to exact versions in production.
• gotcha This utility relies heavily on standard environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`). Ensure these are correctly set and accessible in the Node.js process environment where `configureProxy` is executed. Misconfigured or missing variables will result in no proxy being applied or incorrect proxy behavior.
  Fix: Verify environment variables are properly defined for the Node.js process. On Linux/macOS, use `export VAR=value`; on Windows, use `set VAR=value` or configure system-wide. Always check `process.env` in your application if unsure.
• gotcha The `NO_PROXY` environment variable expects a comma-separated list of hostnames or IPs for which the proxy should not be used. Incorrect patterns (e.g., wildcards not explicitly supported, or incorrect domain matching) can lead to unintended proxying or failure to proxy when expected.
  Fix: Carefully review the `NO_PROXY` documentation (often following `request` library's logic). Test `configureProxy` with various `NO_PROXY` values to ensure desired behavior. Ensure full domain names are listed where appropriate, e.g., `example.com` not just `example`.
• gotcha Axios's built-in `proxy` option only supports HTTP/HTTPS proxies. For SOCKS proxies, an external agent like `socks-proxy-agent` must be used, which `axios-proxy-builder` does not directly integrate.
  Fix: If SOCKS proxies are required, you will need to manually configure Axios with an appropriate agent (e.g., `httpsAgent` or `httpAgent`) and set `proxy: false` to prevent Axios from automatically using environment variables for HTTP/HTTPS proxies. `axios-proxy-builder` is not suitable for SOCKS proxy configuration.

Install

• npm install axios-proxy-builder npm
• yarn add axios-proxy-builder yarn
• pnpm add axios-proxy-builder pnpm

Imports

• configureProxy
  wrong:

  const configureProxy = require('axios-proxy-builder');

  correct:

  import { configureProxy } from 'axios-proxy-builder';

  The library is primarily designed for ESM usage with TypeScript. While CommonJS `require` might work in some transpiled environments, native ESM import is the intended and safest approach.

Quickstart

Demonstrates how to configure standard HTTP proxy environment variables and then use `configureProxy` to apply the detected proxy settings to an Axios GET request.

import axios from 'axios';
import { configureProxy } from 'axios-proxy-builder';

// IMPORTANT: Set these environment variables before running the script
// For example, in your shell:
// export HTTP_PROXY="http://your.proxy.server:8080"
// export NO_PROXY="localhost,127.0.0.1,api.example.com"
// For HTTPS, also set HTTPS_PROXY.

const targetUrl = 'https://api.ipify.org/?format=json'; // A public API to test IP

async function makeProxiedRequest() {
  // Retrieve proxy configuration based on current environment variables
  const proxyConfig = configureProxy(targetUrl);

  try {
    console.log('Attempting request to:', targetUrl);
    if (proxyConfig) {
      console.log('Using proxy configuration:', proxyConfig);
    } else {
      console.log('No proxy configured via environment variables for this URL.');
    }

    const response = await axios.get(targetUrl, {
      proxy: proxyConfig || false, // Pass the generated proxy object, or false if no proxy
    });

    console.log('Response data:', response.data); // Should show the proxy's IP if configured
    console.log('Request successful!');
  } catch (error: any) {
    if (axios.isAxiosError(error)) {
      console.error('Axios Error:', error.message);
      if (error.response) {
        console.error('Status:', error.response.status);
        console.error('Data:', error.response.data);
      } else if (error.request) {
        console.error('No response received:', error.request);
      } else {
        console.error('Error config:', error.config);
      }
    } else {
      console.error('Unexpected Error:', error);
    }
  }
}

// You would typically call this function in your application flow
// For demonstration, we'll call it directly.
makeProxiedRequest();