Fixing Pluralith Graph Errors Behind Corporate Proxies

Nov 19, 2025 by Alex Johnson 55 views

Pluralith Graph Fails Behind Corporate HTTP(S) Proxy: A Comprehensive Guide

Encountering issues with Pluralith graph when operating behind a corporate HTTP(S) proxy? You're not alone. This article delves into the common problem where the pluralith graph command fails due to Axios's limitations in handling HTTPS-over-HTTP proxies. We'll dissect the error, explore the root causes, and provide actionable solutions to get your Pluralith graph working smoothly.

Understanding the Issue

When running pluralith graph in a corporate network that uses an HTTP proxy, you might encounter an error message similar to this:

Error: Request failed with status code 503
    at createError (.../node_modules/axios/lib/core/createError.js:16:15)
    at settle (.../node_modules/axios/lib/core/settle.js:17:12)
    at IncomingMessage.handleStreamEnd (.../node_modules/axios/lib/adapters/http.js:322:11)
    ...
  config: {
    ...
    headers: {
      Accept: 'application/json, text/plain, */*',
      authorization: 'Bearer <masked>',
      'User-Agent': 'axios/0.26.0',
      host: 'api.pluralith.com'
    },
    url: 'https://api.pluralith.com/v1/graph/get/current/version/prod',
    method: 'get',
    ...
  },
  response: {
    status: 503,
    statusText: 'Service Unavailable',
    headers: {
      'proxy-connection': 'close',
      'content-type': 'text/html; charset=utf-8',
      ...
    },
    data: '<HTML> ... (corporate proxy error page, masked) ... </HTML>'
  },
  isAxiosError: true,
  ...
}

generating diagram failed -> GenerateGraph: running CLI command failed -> GenerateDiagram: exit status 1

This error, characterized by a 503 Service Unavailable status code, often indicates that the corporate proxy, rather than api.pluralith.com, is the source of the problem. Let's break down why this happens.

The Root Cause: Axios and HTTPS over HTTP Proxies

The core issue lies in how Axios, the HTTP client library used by Pluralith, handles HTTPS requests through HTTP proxies. Corporate proxies frequently use HTTP CONNECT tunneling to facilitate HTTPS connections. This involves establishing a tunnel through the proxy before sending encrypted traffic to the destination server. However, Axios has known limitations in correctly managing this process. This limitation is documented in several Axios issues, such as axios/axios#3384 and axios/axios#4531, which highlight the challenges in using HTTPS via an HTTP proxy with Axios.

In essence, Axios might not be properly establishing the HTTPS tunnel via the proxy, leading to the proxy rejecting the connection and returning a 503 error. The library may fail to correctly implement the HTTP CONNECT method, which is essential for creating a secure tunnel through the proxy server. This can be a significant hurdle for users operating within corporate networks that rely on proxies for security and access control.

Expected Behavior vs. Reality

The expected behavior is that pluralith graph should seamlessly function behind an HTTP proxy when accessing HTTPS endpoints like https://api.pluralith.com/.... The tool should automatically establish an HTTPS tunnel via the proxy, using the HTTP CONNECT method, and then securely transmit the HTTPS request over that tunnel. This involves correctly negotiating the connection with the proxy, handling authentication if required, and ensuring that the data transmitted remains encrypted throughout the process. The reality, however, is that due to Axios's limitations, this process often breaks down, resulting in the aforementioned errors.

Contextual Background: Axios Limitations

The limitations within Axios concerning HTTPS over HTTP proxies are well-documented within the Axios community. While there's an open pull request ( axios/axios#6465 ) aimed at resolving these issues, it remains unmerged. This ongoing situation underscores the complexity of the problem and the need for alternative solutions in the interim. The PR represents an attempt to enhance Axios's capabilities in handling proxy connections, but until it's integrated, users need to explore workarounds to ensure their applications can function properly behind corporate proxies.

Workarounds and Solutions

Fortunately, the Axios community has proposed several workarounds to address this issue. These solutions primarily involve using external modules that provide robust proxy support, effectively bypassing Axios's inherent limitations. Let's explore two prominent options:

1. Leveraging `global-agent`

global-agent is a powerful module designed to manage proxy configurations globally within your Node.js environment. It automatically detects and applies proxy settings from environment variables like HTTP_PROXY, HTTPS_PROXY, and NO_PROXY. This makes it an ideal solution for applications that need to seamlessly adapt to different network environments. By integrating global-agent, you can ensure that all HTTP(S) requests, including those made by Axios, are routed correctly through the configured proxy.

To implement this solution, follow these steps:

Install global-agent:
```
npm install global-agent --global
```
The --global flag ensures that the package is installed globally, making it available to all your Node.js projects.
Activate global-agent:
```
require('global-agent').bootstrap();
```
Place this line at the beginning of your Pluralith CLI script or any other Node.js application that requires proxy support. This will initialize global-agent and enable it to intercept and manage HTTP(S) requests.
Configure Environment Variables:

Set the appropriate environment variables for your proxy settings. This typically involves defining HTTP_PROXY and HTTPS_PROXY to specify the proxy server's address and port. For example:
```
export HTTP_PROXY=http://your-proxy-address:your-proxy-port
export HTTPS_PROXY=http://your-proxy-address:your-proxy-port
```
If you have hosts or domains that should bypass the proxy, use the NO_PROXY variable:
```
export NO_PROXY=localhost,127.0.0.1,your-internal-domain.com
```
By setting these environment variables, you instruct global-agent to route traffic through the specified proxy server, while excluding the hosts listed in NO_PROXY.

By following these steps, you effectively configure global-agent to handle proxy settings for your Pluralith CLI, ensuring that it can correctly route requests through your corporate proxy server. This approach simplifies proxy management and reduces the likelihood of encountering connection errors.

2. Employing `proxy-agent`

proxy-agent offers a more granular approach to proxy management. Unlike global-agent, which operates globally, proxy-agent allows you to create individual proxy agents for specific Axios instances. This is particularly useful when you need to use different proxies for different requests or when you want to isolate proxy configurations for specific parts of your application. proxy-agent supports various proxy protocols, including HTTP, HTTPS, and SOCKS, providing flexibility in diverse network environments.

Here’s how to use proxy-agent within your Pluralith CLI:

Install proxy-agent:
```
npm install proxy-agent
```
This command installs proxy-agent as a dependency in your project, making it available for use in your code.
Import ProxyAgent and Axios:
```
const { ProxyAgent } = require('proxy-agent');
const axios = require('axios');
```
This imports the necessary modules for creating a proxy agent and making HTTP requests.
Create a ProxyAgent instance:
```
const proxyAgent = new ProxyAgent('http://your-proxy-address:your-proxy-port');
```
Replace 'http://your-proxy-address:your-proxy-port' with the actual address of your proxy server. proxy-agent supports various proxy URL formats, including those with authentication credentials.
Configure Axios to use the ProxyAgent:
```
const axiosInstance = axios.create({
  httpAgent: proxyAgent,
  httpsAgent: proxyAgent,
});
```
This creates a new Axios instance configured to use the proxyAgent for both HTTP and HTTPS requests. By setting the httpAgent and httpsAgent options, you ensure that all requests made with this instance will be routed through the specified proxy.
Use the Axios instance for your requests:
```
axiosInstance.get('https://api.pluralith.com/v1/graph/get/current/version/prod')
  .then(response => {
    // Handle the response
    console.log(response.data);
  })
  .catch(error => {
    // Handle the error
    console.error(error);
  });
```
By using the axiosInstance configured with proxyAgent, you ensure that all requests to api.pluralith.com are routed through your corporate proxy. This allows you to overcome the limitations of Axios's default proxy handling and successfully make requests behind a proxy server.

By implementing these steps, you can effectively use proxy-agent to manage proxy settings for your Pluralith CLI, providing a robust solution for making HTTP(S) requests behind a corporate proxy. This approach offers greater control over proxy configurations and ensures that your application can function correctly in diverse network environments.

Additional Tips for Troubleshooting

Beyond the core workarounds, consider these additional tips to further troubleshoot and resolve proxy-related issues with Pluralith graph:

Verify Proxy Settings: Double-check that your HTTP_PROXY and HTTPS_PROXY environment variables are correctly configured. Ensure the proxy address and port are accurate and that any necessary authentication credentials are included. Incorrect proxy settings are a common cause of connection errors.
Inspect Proxy Logs: Examine your corporate proxy's logs for any error messages or blocked requests related to Pluralith. Proxy logs can provide valuable insights into why a connection is failing and help pinpoint the root cause of the issue. This may require coordination with your network administrator.
Test with a Simple Request: Use a basic tool like curl or wget to make a simple HTTPS request through your proxy. This helps isolate whether the issue is specific to Pluralith or a more general proxy configuration problem. If the simple request fails, the problem likely lies with your proxy setup.
Check Firewall Rules: Confirm that your firewall rules allow traffic to pass through the proxy server and to the Pluralith API endpoints. Firewalls can sometimes block connections, leading to errors similar to those caused by proxy misconfiguration. Ensure that the necessary ports and protocols are allowed.
Update Pluralith CLI: Ensure you are using the latest version of the Pluralith CLI. Newer versions may include bug fixes or improvements related to proxy handling. Regularly updating your CLI can resolve compatibility issues and improve overall performance.

By systematically applying these troubleshooting steps, you can effectively diagnose and resolve proxy-related issues, ensuring that your Pluralith graph operates smoothly within your corporate network.

Conclusion

While Axios's limitations in handling HTTPS over HTTP proxies can present challenges, especially in corporate environments, the workarounds discussed in this article—using global-agent or proxy-agent—offer practical solutions. By implementing these strategies and employing the troubleshooting tips provided, you can overcome these hurdles and ensure that your Pluralith graph functions seamlessly behind a corporate proxy.

For further information on proxy configurations and network troubleshooting, consider exploring resources like the Mozilla documentation on HTTP proxies.