gaxios HTTP Client

Common errors

• ERR_REQUIRE_ESM: require() of ES Module .../node_modules/gaxios/build/src/index.js from ... not supported.

  cause Attempting to use `require()` to import gaxios in a CommonJS module, but gaxios is an ES Module since v5.
  fix Convert your module to ES Module syntax using `import { symbol } from 'gaxios';` and ensure your `package.json` has `"type": "module"` or your file ends with `.mjs`.

• TypeError: fetch failed

  cause This generic error indicates a fundamental network issue, such as a DNS resolution failure, network connectivity loss, firewall blocking the request, or an invalid URL scheme (e.g., `http` where `https` is expected or vice-versa).
  fix Verify network connectivity, check for proxy configurations, ensure the target URL is correct and accessible, and confirm that firewalls are not blocking outbound connections from your application.

• TypeError: Agent is not a constructor

  cause This error can occur if a proxy agent library (like `http-proxy-agent` or `https-proxy-agent`), used internally or explicitly, changes its default export from a constructor to an object with named exports, leading to incorrect instantiation.
  fix Ensure all related dependencies (gaxios, teeny-request, proxy agents) are updated to their latest compatible versions, as this often indicates an incompatibility between versions of underlying networking libraries. If explicitly using an agent, check its documentation for updated instantiation patterns.

• Response data is not as expected (e.g., empty for JSON, or unexpected format) when sending a plain object in `data`.

  cause By default, gaxios attempts to infer the `Content-Type` header when `data` is a plain object, usually setting it to `application/json`. If your API expects a different content type (e.g., `application/x-www-form-urlencoded`) but `data` is an object, gaxios might serialize it as JSON incorrectly.
  fix Explicitly set the `Content-Type` header in your `GaxiosOptions` (e.g., `headers: { 'Content-Type': 'application/x-www-form-urlencoded' }`) when the target API expects a format other than JSON for object payloads. For `URLSearchParams`, pass an instance of `URLSearchParams` to `data`.

Warnings

• breaking gaxios v7 and above require Node.js 18 or newer. Projects running on older Node.js versions (e.g., 16) must either upgrade their Node.js runtime or use an earlier version of gaxios (e.g., v6).
  Fix: Upgrade your Node.js runtime to version 18 or higher. Alternatively, pin gaxios to a compatible version (e.g., `npm install gaxios@6`) if a Node.js upgrade is not feasible.
• breaking gaxios transitioned to an ESM-only package starting from v5. Attempting to use `require()` for imports in a CommonJS module will result in `ERR_REQUIRE_ESM` errors.
  Fix: Ensure your project uses ES Modules (`import/export`) for gaxios or configure your environment (e.g., `package.json` `"type": "module"`) to handle ESM correctly. For existing CommonJS projects, consider using dynamic `import()` or stick to an older version of gaxios if module type conversion is not an option.
• gotcha The `gaxios.defaults` property, when set on a `Gaxios` instance, will take precedence over other authentication methods, including application default credentials. This can lead to unexpected authentication failures if not managed carefully, especially when working with Google APIs.
  Fix: Be mindful when setting `gaxios.defaults.headers.Authorization` or similar authentication headers. If you intend to use `google-auth-library` or other authentication mechanisms, ensure that your custom defaults do not inadvertently override them. Prefer passing authentication details per-request if defaults are broad.
• gotcha The `maxContentLength` option defaults to `0`, which signifies no limit on the response content size, not a zero-byte limit. This can lead to excessive memory consumption for very large responses if not explicitly configured.
  Fix: To prevent unbounded memory usage, set `maxContentLength` to a sensible byte limit (e.g., `10 * 1024 * 1024` for 10MB) in your `GaxiosOptions` if you are expecting potentially large responses.
• gotcha By default, gaxios automatically processes the response body (e.g., JSON, text). If you need to handle the raw response stream (e.g., for large file downloads), this auto-processing needs to be disabled.
  Fix: To receive the response body as a stream, set `responseType: 'stream'` in your `GaxiosOptions`. This will make the `res.data` property a `ReadableStream` (in browsers) or `stream.Readable` (in Node.js).

Install

• npm install gaxios npm
• yarn add gaxios yarn
• pnpm add gaxios pnpm

Imports

• request
  wrong:

  const { request } = require('gaxios');

  correct:

  import { request } from 'gaxios';

  The primary function for making HTTP requests. gaxios is an ESM-only package since v5; CommonJS `require` will lead to errors in modern Node.js.
• instance
  wrong:

  const { instance } = require('gaxios');

  correct:

  import { instance } from 'gaxios';

  Provides a `fetch`-compatible API (`instance.fetch`) and allows setting global defaults on the default instance.
• Gaxios
  wrong:

  const Gaxios = require('gaxios').Gaxios;

  correct:

  import { Gaxios } from 'gaxios';

  Use this class to create new Gaxios instances with custom default configurations, separate from the global `instance`.

Quickstart

This quickstart demonstrates basic GET and POST requests using the default `request` function and a custom `Gaxios` instance, including setting base URLs, headers, and handling timeouts and errors.

import { request, Gaxios } from 'gaxios';

async function makeGaxiosRequests() {
  try {
    // --- Example 1: Basic GET request using the default `request` function ---
    console.log('--- Initiating basic GET request to Google ---');
    const googleResponse = await request({
      url: 'https://www.google.com/search',
      params: { q: 'gaxios library' },
      timeout: 10000 // 10 seconds timeout
    });
    console.log(`Google Search Status: ${googleResponse.status}`);
    console.log(`Google Search Data (partial): ${googleResponse.data.substring(0, 100)}...`);

    // --- Example 2: Using a custom Gaxios instance with base URL and headers ---
    console.log('\n--- Initiating POST request to JSONPlaceholder API ---');
    const jsonPlaceholderClient = new Gaxios({
      baseURL: 'https://jsonplaceholder.typicode.com',
      headers: {
        'Content-Type': 'application/json',
        'User-Agent': 'MyGaxiosApp/1.0'
      },
      timeout: 5000
    });

    const newPostData = {
      title: 'gaxios usage guide',
      body: 'This is a sample post demonstrating gaxios capabilities.',
      userId: 1
    };
    const postResponse = await jsonPlaceholderClient.request({
      url: '/posts',
      method: 'POST',
      data: newPostData
    });
    console.log(`JSONPlaceholder POST Status: ${postResponse.status}`);
    console.log(`Created Post ID: ${postResponse.data.id}, Title: ${postResponse.data.title}`);

  } catch (error: any) {
    console.error('\nAn error occurred during gaxios request:');
    if (error.response) {
      console.error(`Status: ${error.response.status}, Data:`, error.response.data);
    } else if (error.code === 'ERR_SOCKET_TIMEOUT') {
      console.error('Request timed out.');
    } else {
      console.error(error.message);
    }
  }
}

makeGaxiosRequests();