{"id":15695,"library":"make-fetch-happen","title":"make-fetch-happen","description":"make-fetch-happen is an opinionated, robust Node.js HTTP client that extends the standard `fetch` API with critical features for real-world applications. Currently stable at version 15.0.5, it maintains a fairly active release cadence, with minor/patch updates occurring every few months and major versions roughly annually, aligning with Node.js LTS updates. It distinguishes itself by wrapping `minipass-fetch` and augmenting it with capabilities like automatic HTTP-semantics-aware request retries, comprehensive HTTP caching (`Cache-Control`, `ETag`, `304`s, offline fallback), request pooling, transparent gzip/deflate, and support for proxies (HTTP, HTTPS, SOCKS). Additionally, it provides Subresource Integrity (SRI) verification and integrates Node.js Stream support, making it a highly reliable and performant choice for network operations within the Node.js ecosystem, particularly for tools like `npm` itself.","status":"active","version":"15.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/npm/make-fetch-happen","tags":["javascript","http","request","fetch","mean girls","caching","cache","subresource integrity"],"install":[{"cmd":"npm install make-fetch-happen","lang":"bash","label":"npm"},{"cmd":"yarn add make-fetch-happen","lang":"bash","label":"yarn"},{"cmd":"pnpm add make-fetch-happen","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the core fetch API implementation.","package":"minipass-fetch","optional":false},{"reason":"Used for robust HTTP caching on disk.","package":"cacache","optional":false},{"reason":"Manages connection pooling, proxies, and DNS caching.","package":"@npmcli/agent","optional":false},{"reason":"Provides Subresource Integrity (SRI) verification.","package":"ssri","optional":false},{"reason":"Manages automatic request retries.","package":"@gar/promise-retry","optional":false}],"imports":[{"note":"The default export is the fetch function. For CJS, use `require('make-fetch-happen')`.","wrong":"import { fetch } from 'make-fetch-happen';","symbol":"fetch","correct":"import makeFetchHappen from 'make-fetch-happen'; const fetch = makeFetchHappen;"},{"note":"`.defaults` is a method on the default exported fetch function, not a separate named export.","wrong":"import { defaults } from 'make-fetch-happen';","symbol":"fetch.defaults","correct":"import makeFetchHappen from 'make-fetch-happen'; const fetchWithDefaults = makeFetchHappen.defaults({ /* options */ });"},{"note":"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.","wrong":"import { Response } from 'node-fetch';","symbol":"Response","correct":"import makeFetchHappen, { Response } from 'make-fetch-happen'; // Or globally available in Node.js >=18"}],"quickstart":{"code":"import makeFetchHappen from 'make-fetch-happen';\n\nconst fetch = makeFetchHappen.defaults({\n  cachePath: './my-app-cache' // path where cache will be written (and read)\n});\n\n// First request: fetches from the web and caches the response\nfetch('https://registry.npmjs.org/make-fetch-happen')\n  .then(res => res.json()) // download the body as JSON\n  .then(body => {\n    console.log(`Initial fetch: got ${body.name} from web.`);\n    // Second request: forces a conditional request to validate cache\n    return fetch('https://registry.npmjs.org/make-fetch-happen', {\n      cache: 'no-cache' // instructs to revalidate with the origin\n    });\n  })\n  .then(res => {\n    console.log(`Conditional fetch status: ${res.status}`); // Expected 304 if cache valid\n    return res.json().then(body => {\n      console.log(`Conditional fetch: got ${body.name} from cache (status ${res.status}).`);\n    });\n  })\n  .catch(error => console.error('An error occurred:', error));\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=15.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=14.0.0 <15.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"<14.0.3"},{"fix":"Upgrade to `make-fetch-happen@15.0.5` or newer immediately. Review logs generated by previous versions for potential credential exposure.","message":"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.","severity":"gotcha","affected_versions":"<15.0.5"},{"fix":"Upgrade to `make-fetch-happen@14.0.2` or newer to ensure correct handling of request signals with agents.","message":"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.","severity":"gotcha","affected_versions":"<14.0.2"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`).","cause":"The installed Node.js version does not meet the minimum engine requirement specified by make-fetch-happen.","error":"Error: make-fetch-happen requires Node.js version X or higher."},{"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.","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.","error":"SRI Mismatch"},{"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.","cause":"Attempting to call `.defaults` on `makeFetchHappen` when it's not imported correctly, or `makeFetchHappen` itself is undefined due to an incorrect import.","error":"TypeError: makeFetchHappen.defaults is not a function"},{"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.","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.","error":"Proxy error: connect ECONNREFUSED"},{"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.","cause":"The application lacks sufficient write permissions for the specified `opts.cachePath` directory, preventing caching operations.","error":"EACCES: permission denied, open '/path/to/my-app-cache/content-v2/sha512-...' (or similar cache path error)"}],"ecosystem":"npm"}