Global Agent

Common errors

• Error: self signed certificate in certificate chain

  cause The proxy server or target server is using a self-signed or untrusted SSL/TLS certificate, and `global-agent`'s `rejectUnauthorized` is `true` (default since v4.0.0).
  fix Set `GLOBAL_AGENT_SKIP_HTTPS_VALIDATION=true` in your environment variables to bypass certificate validation. Use with caution as it disables security checks. For production, ensure your proxy uses trusted certificates or configure your system to trust the self-signed certificate.

• Proxy is not being used, even with HTTP_PROXY set.

  cause You are likely using the `HTTP_PROXY` environment variable, but `global-agent` expects `GLOBAL_AGENT_HTTP_PROXY` for its bootstrap module.
  fix Export `GLOBAL_AGENT_HTTP_PROXY` (e.g., `export GLOBAL_AGENT_HTTP_PROXY=http://localhost:8080`) instead of `HTTP_PROXY`.

• ERR_UNHANDLED_ERROR: Global agent is already initialized.

  cause The `global-agent/bootstrap` module or the `bootstrap()` function has been called more than once in the application lifecycle.
  fix Ensure `import 'global-agent/bootstrap';` or `bootstrap();` is only executed once. If using conditional logic, wrap it carefully or use `createGlobalProxyAgent` for non-global instances.

• TypeError: (0, global_agent_1.bootstrap) is not a function

  cause This error typically occurs when attempting to use a CommonJS `require()` syntax (e.g., `const { bootstrap } = require('global-agent');`) for named exports in a context where `global-agent` primarily provides ESM named exports, or when a default import was expected but named imports are now required.
  fix Switch to ES module import syntax: `import { bootstrap } from 'global-agent';`. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json` or `.mjs` file extension).

Warnings

• breaking Starting from v4.0.0, `rejectUnauthorized` for TLS connections defaults to `true`. This aligns with Node.js's default behavior but means connections to servers with self-signed or otherwise invalid TLS certificates will now be rejected by default.
  Fix: To allow connections to servers with self-signed certificates, set the environment variable `GLOBAL_AGENT_SKIP_HTTPS_VALIDATION=true`. Be aware of the security implications of disabling certificate validation.
• gotcha The `global-agent/bootstrap` module and `bootstrap()` function primarily rely on `GLOBAL_AGENT_HTTP_PROXY` and `GLOBAL_AGENT_HTTPS_PROXY` environment variables, not the standard `HTTP_PROXY` or `HTTPS_PROXY`.
  Fix: Always use `GLOBAL_AGENT_HTTP_PROXY`, `GLOBAL_AGENT_HTTPS_PROXY`, and `GLOBAL_AGENT_NO_PROXY` environment variables for configuration when using the bootstrap mechanism.
• gotcha `global-agent` is designed to aggressively override any explicitly configured `http.Agent` or `https.Agent` instances that are passed to Node.js's native `http`/`https` modules or popular libraries built on top of them (like `axios`).
  Fix: Be aware that `global-agent` will likely supersede other proxy configurations. If you need fine-grained control over specific requests, consider using `createGlobalProxyAgent` to get a controlled instance or disable `global-agent` for those specific parts of your application.
• breaking Version 4.1.0 changed direct function exports to strictly named exports. While the side-effect `import 'global-agent/bootstrap'` remains, direct imports of functions like `bootstrap` and `createGlobalProxyAgent` must now use named import syntax.
  Fix: Update your import statements to use named exports: `import { bootstrap } from 'global-agent';` or `import { createGlobalProxyAgent } from 'global-agent';`.

Install

• npm install global-agent npm
• yarn add global-agent yarn
• pnpm add global-agent pnpm

Imports

• Side-effect bootstrap
  wrong:

  const globalAgent = require('global-agent/bootstrap');

  correct:

  import 'global-agent/bootstrap';

  This is a side-effect import that initializes the global proxy agent based on environment variables. It's the most common way to set up 'global-agent'.
• bootstrap
  wrong:

  const { bootstrap } = require('global-agent');

  correct:

  import { bootstrap } from 'global-agent';

  Use this named import if you need to explicitly control when the agent is bootstrapped, such as conditionally.
• createGlobalProxyAgent
  wrong:

  const { createGlobalProxyAgent } = require('global-agent');

  correct:

  import { createGlobalProxyAgent } from 'global-agent';

  Use this named import to create a controlled instance of the global proxy agent without affecting the global scope or relying on `global.GLOBAL_AGENT`.
• GlobalAgent
  wrong:

  import { GLOBAL_AGENT } from 'global-agent';

  correct:

  declare var global: { GLOBAL_AGENT: GlobalProxyAgent };

  After `bootstrap` or `global-agent/bootstrap` is called, the configuration object is available at `global.GLOBAL_AGENT`. It is not directly exportable via named imports.

Quickstart

Demonstrates how to enable global HTTP/HTTPS proxying using the side-effect import and environment variables, then makes a sample HTTP request.

import 'global-agent';
import http from 'node:http';

// Simulate setting the environment variable
process.env.GLOBAL_AGENT_HTTP_PROXY = process.env.GLOBAL_AGENT_HTTP_PROXY ?? 'http://127.0.0.1:8080';

console.log(`Global agent will use proxy: ${process.env.GLOBAL_AGENT_HTTP_PROXY}`);

// In a real scenario, you'd run this script with the environment variable set:
// export GLOBAL_AGENT_HTTP_PROXY=http://127.0.0.1:8080 && node your-script.js

// To explicitly bootstrap if not using the side-effect import:
// import { bootstrap } from 'global-agent';
// bootstrap();

const options = {
  hostname: 'example.com',
  port: 80,
  path: '/',
  method: 'GET'
};

const req = http.request(options, (res) => {
  console.log(`STATUS: ${res.statusCode}`);
  console.log(`HEADERS: ${JSON.stringify(res.headers)}`);
  res.setEncoding('utf8');
  let data = '';
  res.on('data', (chunk) => {
    data += chunk;
  });
  res.on('end', () => {
    console.log('Response body length:', data.length);
  });
});

req.on('error', (e) => {
  console.error(`Problem with request: ${e.message}`);
});

req.end();