Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
fetch
✓ import makeFetchHappen from 'make-fetch-happen'; const fetch = makeFetchHappen;
✗ import { fetch } from 'make-fetch-happen';
The default export is the fetch function. For CJS, use `require('make-fetch-happen')`.
fetch.defaults
✓ import makeFetchHappen from 'make-fetch-happen'; const fetchWithDefaults = makeFetchHappen.defaults({ /* options */ });
✗ import { defaults } from 'make-fetch-happen';
`.defaults` is a method on the default exported fetch function, not a separate named export.
Response
✓ import makeFetchHappen, { Response } from 'make-fetch-happen'; // Or globally available in Node.js >=18
✗ import { Response } from 'node-fetch';
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.
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));
Debug
Known issues
breakingVersion 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.fixUpgrade your Node.js environment to version 20.17.0 or higher, or to 22.9.0 or higher. For continuous integration, update environment configurations.
affects: >=15.0.0
breakingVersion 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.fixUpgrade 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.
affects: >=14.0.0 <15.0.0
gotchaPrior 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.fixUpgrade 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`.
affects: <14.0.3
gotchaVersion 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.fixUpgrade to `make-fetch-happen@15.0.5` or newer immediately. Review logs generated by previous versions for potential credential exposure.
affects: <15.0.5
gotchaBefore 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.fixUpgrade to `make-fetch-happen@14.0.2` or newer to ensure correct handling of request signals with agents.
affects: <14.0.2
Errors
Common errors & fixes
Error: make-fetch-happen requires Node.js version X or higher.
The installed Node.js version does not meet the minimum engine requirement specified by make-fetch-happen.
fixUpgrade 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
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.
fixVerify 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
Attempting to call `.defaults` on `makeFetchHappen` when it's not imported correctly, or `makeFetchHappen` itself is undefined due to an incorrect import.
fixEnsure 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
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.
fixDouble-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)
The application lacks sufficient write permissions for the specified `opts.cachePath` directory, preventing caching operations.
fixEnsure 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.
Audit
Dependencies
minipass-fetchrequiredProvides the core fetch API implementation.
cacacherequiredUsed for robust HTTP caching on disk.
@npmcli/agentrequiredManages connection pooling, proxies, and DNS caching.
ssrirequiredProvides Subresource Integrity (SRI) verification.
@gar/promise-retryrequiredManages automatic request retries.