Follow Redirects

Common errors

• Error: Too many redirects. Max of 21 reached.

  cause The HTTP/HTTPS request encountered more redirects than the configured `maxRedirects` limit.
  fix Inspect the URL chain for infinite redirects or increase the `maxRedirects` option if a higher number of legitimate redirects is expected (e.g., `options.maxRedirects = 30;`).

• Error: Request body exceeded maxBodyLength limit.

  cause The size of the data being sent in the request body exceeded the configured `maxBodyLength` limit.
  fix Reduce the size of the request body, or increase the `maxBodyLength` option if larger payloads are necessary (e.g., `options.maxBodyLength = 50 * 1024 * 1024;` for 50MB).

• ReferenceError: require is not defined

  cause Attempting to use `require()` syntax in an ES Module (ESM) context.
  fix Ensure your project is configured for CommonJS, or use dynamic `import()` if you absolutely need to load `follow-redirects` in an ESM context, though its primary API is CommonJS-oriented.

Warnings

• gotcha Exceeding the `maxRedirects` limit (default: 21) will cause an error to be emitted instead of returning a response. Ensure your requests do not enter infinite redirect loops or exceed this count for valid reasons, and handle the error.
  Fix: Increase `maxRedirects` in your options if legitimate redirects exceed the default, or investigate the target URL for misconfigurations causing excessive redirects.
• gotcha Sending a request body larger than `maxBodyLength` (default: 10MB) will result in an error. This prevents potential denial-of-service attacks or accidental oversized uploads.
  Fix: Increase `maxBodyLength` in your options if you legitimately need to send larger request bodies, or ensure your request body size is within limits.
• gotcha Global options (`followRedirects.maxRedirects`, `followRedirects.maxBodyLength`) affect all subsequent requests made via `follow-redirects` unless explicitly overridden by per-request options. This can lead to unexpected behavior if not managed carefully in a shared environment.
  Fix: Always use per-request options (`options.maxRedirects`, `options.maxBodyLength`) when specific limits are required, or when running in an environment where other parts of the application might use `follow-redirects` with different expectations.
• gotcha The `responseUrl` property on the `response` object provides the final URL after all redirects have been followed. The original request URL is not directly available on the final response object; if needed, it must be stored prior to the request.
  Fix: If you need both the original and final URLs, capture the initial request URL before making the call.

Install

• npm install follow-redirects npm
• yarn add follow-redirects yarn
• pnpm add follow-redirects pnpm

Imports

• { http, https }
  wrong:

  import { http, https } from 'follow-redirects';

  correct:

  const { http, https } = require('follow-redirects');

  Primary usage is CommonJS, reflecting the module's origins and common Node.js integration patterns. While ESM import may work with transpilers, `require` is the canonical and most reliable method.
• followRedirects (module object)
  wrong:

  import followRedirects from 'follow-redirects';

  correct:

  const followRedirects = require('follow-redirects');

  Use this pattern to access and configure global options like `followRedirects.maxRedirects` or `followRedirects.maxBodyLength`.
• Types (for TypeScript)

  import type { HttpOptions, HttpsOptions, RedirectOptions, ClientRequest, IncomingMessage } from 'follow-redirects';

  The package ships with TypeScript declarations, allowing for type-safe usage of its options and interfaces.

Quickstart

This quickstart demonstrates basic GET and POST requests using `follow-redirects`, showing how to retrieve the final URL after redirects and how to configure both global and per-request options for maximum redirects and body length.

const { http, https } = require('follow-redirects');
const url = require('url');

// Example 1: Simple GET request with redirect following
// Using a reliable test service for redirects
http.get('http://httpbin.org/redirect/3', response => {
  console.log(`GET Status Code: ${response.statusCode}`);
  console.log(`GET Final URL: ${response.responseUrl}`);
  let data = '';
  response.on('data', chunk => {
    data += chunk;
  });
  response.on('end', () => {
    console.log('GET Response body length:', data.length);
  });
}).on('error', err => {
  console.error('GET Error:', err.message);
});

// Example 2: POST request demonstrating global and per-request options
// Setting global max redirects (default is 21)
followRedirects.maxRedirects = 5; 
// Setting global max body length (default is 10MB)
followRedirects.maxBodyLength = 1 * 1024 * 1024; // 1 MB

const postOptions = url.parse('https://postman-echo.com/post');
postOptions.method = 'POST';
postOptions.headers = {
  'Content-Type': 'application/json',
  'User-Agent': 'follow-redirects-example/1.0'
};
// Override global maxRedirects for this specific POST request
postOptions.maxRedirects = 2;

const postData = JSON.stringify({ message: 'Hello from follow-redirects!', source: 'quickstart' });

const postReq = https.request(postOptions, response => {
  console.log(`POST Status Code: ${response.statusCode}`);
  console.log(`POST Final URL: ${response.responseUrl}`);
  let data = '';
  response.on('data', chunk => {
    data += chunk;
  });
  response.on('end', () => {
    console.log('POST Response body:', JSON.parse(data));
  });
}).on('error', err => {
  console.error('POST Error:', err.message);
});

postReq.write(postData);
postReq.end();