make-fetch-happen

Common errors

• Error: make-fetch-happen requires Node.js version X or higher.

  cause The installed Node.js version does not meet the minimum engine requirement specified by make-fetch-happen.
  fix Upgrade your Node.js environment to the version specified in the error message or the package's `engines` field (e.g., `nvm install 20` and `nvm use 20`).

• SRI Mismatch

  cause The Subresource Integrity (SRI) hash provided in the fetch options does not match the hash of the downloaded resource, indicating potential tampering or an incorrect hash.
  fix Verify the integrity hash (`opts.integrity`) against the actual resource's hash. If the resource has changed, generate a new SRI hash. If fetching a known resource, ensure the integrity hash is correct.

• TypeError: makeFetchHappen.defaults is not a function

  cause Attempting to call `.defaults` on `makeFetchHappen` when it's not imported correctly, or `makeFetchHappen` itself is undefined due to an incorrect import.
  fix Ensure you are importing the default export: `import makeFetchHappen from 'make-fetch-happen';` for ESM or `const makeFetchHappen = require('make-fetch-happen');` for CommonJS.

• Proxy error: connect ECONNREFUSED

  cause make-fetch-happen failed to establish a connection through the configured proxy server, often due to an incorrect proxy address, port, or an unresponsive proxy.
  fix Double-check your `opts.proxy` configuration, including the protocol (http, https, socks) and credentials. Ensure the proxy server is running and accessible from your environment.

• EACCES: permission denied, open '/path/to/my-app-cache/content-v2/sha512-...' (or similar cache path error)

  cause The application lacks sufficient write permissions for the specified `opts.cachePath` directory, preventing caching operations.
  fix Ensure the user running the Node.js process has read/write permissions to the `cachePath` directory. Consider changing the `cachePath` to a user-specific temporary directory or a location with appropriate permissions.

Warnings

• breaking Version 15.0.0 updated the minimum Node.js engine requirement to `^20.17.0 || >=22.9.0`. Older Node.js versions are no longer supported.
  Fix: Upgrade your Node.js environment to version 20.17.0 or higher, or to 22.9.0 or higher. For continuous integration, update environment configurations.
• breaking Version 14.0.0 updated the minimum Node.js engine requirement to `^18.17.0 || >=20.5.0`. Older Node.js versions are no longer supported.
  Fix: Upgrade your Node.js environment to version 18.17.0 or higher, or to 20.5.0 or higher. Verify compatibility with other dependencies before upgrading.
• gotcha Prior to v14.0.3, `make-fetch-happen` could incorrectly ignore the `NODE_TLS_REJECT_UNAUTHORIZED` environment variable when the `strictSSL` option was not explicitly defined, potentially leading to insecure connections.
  Fix: Upgrade to `make-fetch-happen@14.0.3` or newer. Explicitly set `strictSSL: true` in options if you rely on the default secure behavior and want to ensure it's not overridden by `NODE_TLS_REJECT_UNAUTHORIZED=0`.
• gotcha Version 15.0.5 included a fix for URL logging of npm credentials. This implies that prior versions might have inadvertently logged sensitive credential information in URLs under certain conditions.
  Fix: Upgrade to `make-fetch-happen@15.0.5` or newer immediately. Review logs generated by previous versions for potential credential exposure.
• gotcha Before v14.0.2, there were issues where the request signal (for aborting requests) was incorrectly used within the agent, potentially leading to unexpected request termination or resource leaks.
  Fix: Upgrade to `make-fetch-happen@14.0.2` or newer to ensure correct handling of request signals with agents.

Install

• npm install make-fetch-happen npm
• yarn add make-fetch-happen yarn
• pnpm add make-fetch-happen pnpm

Imports

• fetch
  wrong:

  import { fetch } from 'make-fetch-happen';

  correct:

  import makeFetchHappen from 'make-fetch-happen'; const fetch = makeFetchHappen;

  The default export is the fetch function. For CJS, use `require('make-fetch-happen')`.
• fetch.defaults
  wrong:

  import { defaults } from 'make-fetch-happen';

  correct:

  import makeFetchHappen from 'make-fetch-happen'; const fetchWithDefaults = makeFetchHappen.defaults({ /* options */ });

  `.defaults` is a method on the default exported fetch function, not a separate named export.
• Response
  wrong:

  import { Response } from 'node-fetch';

  correct:

  import makeFetchHappen, { Response } from 'make-fetch-happen'; // Or globally available in Node.js >=18

  While `make-fetch-happen` wraps `minipass-fetch` (which provides `Response`), in recent Node.js versions, `Response` is globally available. If needed for type hinting or specific imports, `make-fetch-happen` re-exports it.

Quickstart

This quickstart demonstrates how to configure `make-fetch-happen` with a persistent cache path and perform both initial and conditional HTTP requests, showcasing its caching capabilities.

import makeFetchHappen from 'make-fetch-happen';

const fetch = makeFetchHappen.defaults({
  cachePath: './my-app-cache' // path where cache will be written (and read)
});

// First request: fetches from the web and caches the response
fetch('https://registry.npmjs.org/make-fetch-happen')
  .then(res => res.json()) // download the body as JSON
  .then(body => {
    console.log(`Initial fetch: got ${body.name} from web.`);
    // Second request: forces a conditional request to validate cache
    return fetch('https://registry.npmjs.org/make-fetch-happen', {
      cache: 'no-cache' // instructs to revalidate with the origin
    });
  })
  .then(res => {
    console.log(`Conditional fetch status: ${res.status}`); // Expected 304 if cache valid
    return res.json().then(body => {
      console.log(`Conditional fetch: got ${body.name} from cache (status ${res.status}).`);
    });
  })
  .catch(error => console.error('An error occurred:', error));