Configuring Axios for HTTPS Requests Through a Proxy Server: Issues and Solutions

Problem Background and Symptom Description

In modern web development, using proxy servers for network requests is a common requirement, especially in enterprise environments or scenarios needing to bypass geographical restrictions. Axios, as a popular JavaScript HTTP client library, offers proxy configuration support, but developers may encounter issues where proxy settings do not work as expected. Based on user feedback from Stack Overflow, a typical scenario is: a developer attempts to send a request to an HTTPS endpoint (e.g., https://api.ipify.org?format=json) via Axios with proxy configuration, but the response returns the local IP address instead of the proxy server's IP, indicating the proxy configuration was not applied correctly.

User Attempts and Failure Reasons

The user initially tried two configuration approaches. The first was using Axios's built-in proxy option:

const axios = require('axios');

var res = await axios.get('https://api.ipify.org?format=json', {
    proxy: {
        host: 'proxy-url',
        port: 80,
        auth: {username: 'my-user', password: 'my-password'}
    }
});
console.log(res.data); // Returns local IP, not proxy IP

This method should theoretically route requests through the proxy, but in testing, the proxy did not take effect. The user then tried the axios-https-proxy-fix library, a community-maintained patch version, which also failed to resolve the issue.

The second attempt involved creating a custom proxy agent using the https-proxy-agent module:

const axios = require('axios');
const HttpsProxyAgent = require('https-proxy-agent')

var agent = new HttpsProxyAgent('http://my-user:my-pass@proxy-url:port');
var res = await axios.get('https://api.ipify.org?format=json', {
    httpsAgent: agent,
});
console.log(res.data); // Still returns local IP

Despite using the httpsAgent configuration, the problem persisted, leading the user to question whether Axios itself has a bug.

Core Issue Analysis: Axios Proxy Bug

According to Issue #2072 on Axios's official GitHub repository, this problem has been confirmed as a bug, marked since March 31, 2020. This bug primarily affects proxy configuration for HTTPS requests, causing proxy settings to be ignored or mishandled. The root cause lies in Axios's internal handling of proxy configuration, which may not correctly apply proxy agents to HTTPS connections, particularly in certain Node.js environments or browser compilation scenarios. This explains why users cannot achieve the expected results even with https-proxy-agent.

The existence of this bug means developers cannot rely on Axios's standard proxy configuration for HTTPS requests and must seek workarounds or alternatives. In the open-source community, such issues are typically addressed through issue tracking and patch releases, but as of the data collection, it remains unresolved.

Effective Solution: Correct Usage of https-proxy-agent

Although the user's attempt with https-proxy-agent failed, based on supplementary answers, proper configuration can solve the problem. The key step is to create a custom Axios instance using axios.create and integrate the proxy agent into the configuration:

const HttpsProxyAgent = require("https-proxy-agent"),
      axios = require("axios");

const httpsAgent = new HttpsProxyAgent({
    host: "proxyhost", 
    port: "proxyport", 
    auth: "username:password"
})

// Create a custom Axios instance and specify httpsAgent
const axiosInstance = axios.create({httpsAgent});

// Use this instance to send requests
var res = await axiosInstance.get('https://api.ipify.org?format=json');
console.log(res.data); // Should return proxy IP

This approach ensures the proxy agent is correctly applied to all requests via axios.create, avoiding potential overrides in direct configuration. Note that the proxy URL should use the HTTP protocol (e.g., http://proxyhost:proxyport), even for HTTPS target requests, as the proxy server handles protocol conversion.

Alternatives and Best Practices

If Axios's bug continues to impact a project, developers can consider using the Fetch API as an alternative. The Fetch API is natively supported in modern browsers and applicable in Node.js environments (via libraries like node-fetch). Example code:

// Using Fetch API in browser or Node.js
fetch('https://api.ipify.org?format=json', {
    agent: new HttpsProxyAgent('http://my-user:my-pass@proxy-url:port')
})
.then(response => response.json())
.then(data => console.log(data));

The Fetch API is generally lighter and more standard, but may lack some advanced features of Axios, such as interceptors. When choosing a solution, developers should assess project needs: if dependent on Axios-specific features, try the workaround above; otherwise, the Fetch API may be a more stable choice.

Additionally, developers are advised to monitor updates in the Axios GitHub repository for bug fixes. Participating in community discussions or adding details to the issue thread can help the development team prioritize this problem.

Conclusion and Recommendations

The bug in Axios for HTTPS requests through proxies is a known issue affecting many developers' workflows. By using https-proxy-agent with axios.create, it is possible to effectively bypass this bug and achieve proxy functionality. Meanwhile, the Fetch API offers a reliable alternative. In development, thorough testing is recommended to ensure proxy configuration works correctly in the target environment, and staying updated on library changes is crucial to leverage future fixes and improvements.