got
16.2.0 · 30 Oct 2026MIT53.2M / weekRepositoryHomepagenpmAtom feed
188 stable releases, newest first, by release line. Notes are quoted as the maintainers published them.
- 16.x · latest line
16.1.0
13 Oct 2026Invalid options now throw: an empty
method, a negative or fractionalmaxRedirectsorretry.limit, aprefixUrlwith a query string or fragment, and ahandlersentry that is not a function.A stream with a
body,json, orformoption now rejects writes, as documented.The promise
responseevent now only fires for the final response, not for every retry attempt.
This release is the result of a large bug hunt. Many of the fixes make Got match its documented behavior, so you may notice some of them:
Invalid options now throw: an empty
method, a negative or fractionalmaxRedirectsorretry.limit, aprefixUrlwith a query string or fragment, and ahandlersentry that is not a function.A stream with a
body,json, orformoption now rejects writes, as documented.The promise
responseevent now only fires for the final response, not for every retry attempt.got.extend({body})(andjson,form) no longer sends the payload with every request of the instance. Payloads are never merged with defaults.instance.extend()now inherits the parent'smutableDefaults, likegot.extend(instance).A
HEADrequest is no longer changed toGETon a301,302, or303redirect.response.bodyno longer keeps a leading UTF-8 byte order mark, and JSON with a byte order mark now parses.
Improvements
Accept number values in
headers6fffc9eExport the
Timings,DnsCacheLookup, andDnsCacheOptionstypes d012d1d eccaacaRetry
FormDatabodies by re-serializing them instead of failing 90c6ec1Support the
x-gzipcontent coding and stacked content codings 5550a79
Fixes
Fix many HTTP/2 edge cases, including requests that could hang forever when the response or request was destroyed d3c549c 78bf394 6bbc7f4 602b179 687b5c8 4ea02b8 b6522f3 9348ad6 c686386 3bbc37b 91dc486 11621cd
Fix
timeout.requestrestarting on each redirect, and several timeout phase edge cases 9cd2ee6 df33cdb 4e4c583 795234f 0f1263dFix redirects: keep the URL fragment, evaluate
followRedirectonce per response, and keepContent-Lengthcorrect when a hook replaces the body 1febf3c a2b3d90 1d64f7c 60b48afFix
Infinitytimeouts firing at once or throwing 724ebc2Fix retry delay edge cases, including invalid
Retry-Aftervalues andcalculateDelayforafterResponseretries fe58b8c 0193605Fix retries with replaced or non-replayable bodies ae5521f 7c1cda3 8bbc79f 1a56d36 d012d1d
Fix the default
paginateon real-worldLinkheaders, and several pagination option and limit edge cases bd2dee0 1e61807 602b179 f98d0e1 c8419e4 526a988 557e61f 4712e5b a4a50ad b65e533Fix
afterResponse,beforeRequest, andbeforeCachehook edge cases 45c201c c1cf0f8 850e49b a4a50ad 863cf30 494279bFix response body decoding and parsing edge cases c36ad51 c409a84 3c6eaf1 f658d3e dbd83df
Fix stream edge cases: respect backpressure, stop forwarding after unpipe, and do not copy hop-by-hop headers to a piped
ServerResponse348e114 dc929bd dc56e4b c930cd9 a9a754fFix uploads:
DataViewbyte ranges, upload error classification, progresstotalforContent-Length: 0, and cancelling WebReadableStreambodies 2a66686 d1cb051 0238069 b57120c 200bc85Fix option normalization, cloning, and immutable defaults 8f44d81 687eb7d 30023f7 5548b00 bec5da6 bcc0b01 9348ad6 a9a754f 7b13369 3bd0486 d272656 0e537c7 60b62a0 129d88d
Fix error stacks reporting
RequestErrorinstead of the real error class, and other error cause edge cases c8419e4 9d61a37 5ccac58 71f4e0eFix custom DNS cache lookups and DNS records without a valid TTL b3dc5c6 4ea02b8 d012d1d
Fix cookie edge cases with retries, redirects, and async cookie jars 784bbd2 d5cd5e4
Fix diagnostics channel coverage across retries and terminal errors cfce7b6
Fix TypeScript types to match the runtime values 7c833b8 c59692b 88eeb13 0c17a8b c788ac9 a4176b6
16.0.0
30 Aug 2026Breaking changes
- Breaking
Rewrite HTTP/2 support and drop the
http2-wrapperdependency (#2464) 1e157c4Got now has a built-in HTTP/2 client: ALPN negotiation, a pooled session cache with multiplexing,
GOAWAYretirement, request and response trailers, informational (1xx) responses, abort signals, response caching, IPv6 authorities, andh2cthroughh2session.agent.http2is no longer an agent slot. It is only an opt-out flag now: passfalseto skip session pooling. Passing an agent instance throws.Response headers no longer contain HTTP/2 pseudo-headers. Use
response.statusCodeinstead ofresponse.headers[':status'].A custom
agent.httpscombined withhttp2: truemakes Got use the native HTTP/1.1 path, because the built-in session pool does not support custom HTTPS agents.HTTP/2 proxy support is gone. It came from
http2-wrapper. It was very buggy anyway.If
options.requestreturns a request or response, it controls the transport and the HTTP/2 client is bypassed. Returnundefinedto fall back to Got's own transport.
- Breaking
Rewrite DNS cache and drop the
cacheable-lookupdependency (#2463) bfc400bdnsCache: truenow uses Got's own cache. The option accepts any object with alookupfunction and an optionalclear(hostname?)function, so an existingCacheableLookupinstance still works if you keep the dependency yourself.The built-in cache resolves A and AAAA records separately, so it cannot preserve OS-specific
verbatimaddress ordering fromdns.lookup().
- Breaking
A
beforeRequesthook, anafterResponseretry, or a pagination step that moves the request to a different origin now strips credentials and drops the body (#2465) dd3b295authorization,cookie,cookie2,host, andproxy-authorizationare removed, URL credentials are dropped, and an unchanged body is cleared. Set the headers or body explicitly inside the hook if you want them to cross the origin boundary.This applies whether the origin changes through
urlor throughprefixUrl.
- Breaking
copyPipedHeadersno longer copies credentials 1d233baauthorization,cookie,cookie2,set-cookie, andset-cookie2are now omitted along withhost, the hop-by-hop headers, and anything nominated byConnection/Proxy-Connection. Pass credentials explicitly inheaderswhen the upstream is trusted.
- Breaking
Remove the deprecated
searchParameters,followRedirects, andauthoption stubs 1d233baThey only existed to throw a guidance message. Passing them now throws
Unexpected option: ….
- Breaking
Remove the
OptionsOfUnknownResponseBodytype 1d233baIt was a pure alias for
StrictOptions.
Improvements
Add support for the
QUERYHTTP method (#2466) e3924aaAdds
got.query()andgot.stream.query().QUERYis safe and idempotent, so it is retried by default and keeps a replayable body across301and302redirects as well as307and308. It is not stored by the built-in cache, because correctQUERYcaching needs cache keys that include the request content.
allowGetBodynow also works over HTTP/2 1e157c4timeout.socketnow applies during HTTP/2 TLS negotiation and session setup c6bbb8aIt was previously folded into the connection setup timeout and reported as a
requesttimeout. It now produces a realsockettimeout and no longer counts DNS lookup time.
Two fewer dependencies:
cacheable-lookupandhttp2-wrapperbfc400b 1e157c4
Fixes
Retry on connection errors reported by
request.end()instead of failing the request (#2470) 67919b2Retry immediately when the server answers with
Retry-After: 0instead of falling back to the backoff delay (#2471) d35ce87Preserve the response body when a cookie jar write throws c6bbb8a
error.response.bodyis now complete, decompressed, and decoded with the configuredencoding, and a decoding failure no longer masks the original error.
Wait for async cookie jar writes on terminal redirect responses, for example with
followRedirect: falsec6bbb8aOnly buffer the response body for cookie handling when the response actually sends
set-cookiec6bbb8aFix
got.streamfinalizing the response before theresponseevent and before piped server response headers are set c6bbb8aFix
strictContentLengthcounting bytes from responses that were not actually decompressed c6bbb8aFreeze
hooks.beforeCachealong with the other hook arrays on non-mutable defaults 1d233baKeep URL credentials when
prefixUrlis changed to a same-origin value, and treat credentials inprefixUrlas explicit dd3b295
Migration guide
HTTP/2
Remove
http2-wrapperfrom your code. Got's HTTP/2 client is built in.Before:
import http2wrapper from 'http2-wrapper'; const {headers} = await got(url, { http2: true, request: http2wrapper.auto, agent: { http2: new http2wrapper.Agent() } }); console.log(headers[':status']);After:
const {statusCode} = await got(url, {http2: true}); console.log(statusCode);To opt out of HTTP/2 session pooling for a request, set
agent.http2tofalse.If you need an HTTP/2 proxy, keep using
http2-wrapperthrough therequestoption. Returning a request fromrequestbypasses Got's HTTP/2 client.h2cThe
h2sessionhook example no longer needsrequestorhttp2.Before:
import http2 from 'http2-wrapper'; got.extend({ hooks: { beforeRequest: [ options => { options.h2session = getSession(options.url); options.http2 = true; options.request = http2.request; } ] } });After:
got.extend({ hooks: { beforeRequest: [ options => { options.h2session = getSession(options.url); } ] } });dnsCachednsCache: truekeeps working and now uses Got's built-in cache. If you depend oncacheable-lookupspecific options, install it yourself and pass the instance:import CacheableLookup from 'cacheable-lookup'; const dnsCache = new CacheableLookup({maxTtl: 60}); await got(url, {dnsCache});Cross-origin hooks
If a
beforeRequesthook, anafterResponseretry, or a pagination step sends the request to a different origin, set the headers and body you want to keep explicitly:got.extend({ hooks: { beforeRequest: [ options => { options.url = new URL('https://other.example.com/path'); options.headers.authorization = 'Bearer …'; } ] } });copyPipedHeadersCredentials are no longer forwarded from a piped request. Pass them explicitly when the upstream is trusted:
got.stream(url, { copyPipedHeaders: true, headers: { authorization: request.headers.authorization } });- 15.x
15.1.0
2 Jul 2026Add
allowAbsoluteUrlsoption (#2462) 1c88e88
15.0.0
1 Apr 2026- Breaking
Require Node.js 22 b933476
- Breaking
Remove promise cancel API a06ac6c
- Breaking
Remove
isStreamoption c241c6c
Breaking changes
- Breaking
Require Node.js 22 b933476
- Breaking
Remove promise cancel API a06ac6c
promise.cancel()is gone. Use thesignaloption withAbortControllerinstead.
- Breaking
Remove
isStreamoption c241c6cUse
got.stream()directly.
- Breaking
Use native
FormDataglobal 670b228Use the Web API
FormDataglobal directly (available in Node.js 18+).
- Breaking
responseType: 'buffer'returnsUint8Arrayinstead ofBuffer309e36dresponse.rawBodyandpromise.buffer()now return aUint8Array.Bufferis a subclass ofUint8Array, so most code will continue to work, but strict type checks will need updating.
- Breaking
strictContentLengthdefaults totrue08e9dffGot now throws a
ContentLengthMismatchErrorby default ifContent-Lengthdoesn't match the actual body size. Set{strictContentLength: false}to restore the old behavior.
- Breaking
retry.enforceRetryRulesdefaults totrue9bc8dfbCustom
calculateDelayfunctions are now only called when a retry is actually allowed bylimit,methods,statusCodes, anderrorCodes. If yourcalculateDelaywas previously used to override retry eligibility unconditionally, set{retry: {enforceRetryRules: false}}.
- Breaking
Piped header copying is now opt-in 8e392f3
Got no longer automatically copies headers from a piped stream. Set
{copyPipedHeaders: true}to re-enable. Hop-by-hop headers are never copied even when enabled (RFC 9110 §7.6.1).
- Breaking
urlremoved from public options objects 87de8d6The
urlproperty is no longer present on the options object passed to hooks. Useresponse.urlorrequest.requestUrlinstead.
- Breaking
300 and 304 responses are no longer auto-followed 5fccaab
Per RFC 9110, 304 is a conditional-GET hint, not a redirect, and 300 is only a SHOULD for user agents. Got now returns these responses as-is. Handle them manually if needed.
- Breaking
Removed the undocumented named export for Got.
Got has always been a default export. The named export was there only for buggy build tools during the ESM migration times.
Improvements
Stream decode large
text/jsonbodies incrementally for lower peak memory usage c9a95b1uploadProgressnow emits granular per-chunk events forjsonandformrequest bodies 13c889d
Migration guide
Replace
promise.cancel()withAbortControllerBefore:
const promise = got(url); promise.cancel();
After:
const controller = new AbortController(); const promise = got(url, {signal: controller.signal}); controller.abort();Replace
isStream: truewithgot.stream()Before:
got(url, {isStream: true});After:
got.stream(url);
Replace
form-data/form-data-encoderwith nativeFormDataBefore:
import {FormData} from 'formdata-node'; // or: import {FormData} from 'formdata-polyfill/esm.min.js'; const form = new FormData(); form.set('name', 'value'); await got.post(url, {body: form});After:
const form = new FormData(); form.set('name', 'value'); await got.post(url, {body: form});Update
Bufferusage toUint8Arrayresponse.rawBodyandpromise.buffer()now returnUint8Arrayinstead ofBuffer.Before:
const data = await got(url).buffer(); const copy = Buffer.from(data);
After:
const data = await got(url).buffer(); const copy = new Uint8Array(data);
If you need
Buffer-specific APIs, wrap withBuffer.from(data.buffer, data.byteOffset, data.byteLength).strictContentLengthis now on by defaultIf you send requests where the
Content-Lengthheader might not match the actual body size, opt out:got.extend({strictContentLength: false});retry.enforceRetryRulesis now on by defaultIf your
calculateDelayfunction was overriding retry eligibility (e.g. retrying on methods or status codes outside the defaults), opt out:got.extend({ retry: { enforceRetryRules: false, calculateDelay: ({computedValue}) => { // computedValue is 0 when retry is not allowed if (computedValue === 0) { return 0; } return computedValue; }, }, });Piped header copying is now opt-in
If you pipe streams into Got and rely on automatic header forwarding (e.g.
Content-Type), re-enable it:got.extend({copyPipedHeaders: true});300 and 304 responses are no longer followed
If your code depended on Got auto-following 300 Multi-Choice or handling 304 Not Modified as a redirect, you now need to handle them yourself in an
afterResponsehook or checkresponse.statusCodemanually.- 14.x
14.6.1
25 Oct 2025Fix the TS code not being built in 14.6.0.
14.6.0
16 Oct 2025Add
beforeCachehook 1c3a041Add
retryCounttobeforeRequesthook context 91cdc48Improve
HTTPErrormessage to include method and URL 6dd7574
Improvements
Add
beforeCachehook 1c3a041Add
retryCounttobeforeRequesthook context 91cdc48Improve
HTTPErrormessage to include method and URL 6dd7574Add support for typed arrays as request body ecf5633
Add Node.js diagnostic channel support 3e2a781
Allow custom Error classes in
beforeErrorhook 1c71194Add zstd (Zstandard) compression support 449833a
Improve validation error messages by including option names f5c54a3
Add
strictContentLengthoption 4206f0eAdd support for
https.secureOptionsoption 7ec1714Add
copyPipedHeadersoption to control automatic header copying from piped streams d83daddAdd
stream.isReadonlyproperty to detect read-only streams 030dfbb
Fixes
Fix HTTP/2 timings NaN issue 398c11a
Fix shortcut methods ignoring handler errors f004564
Fix body reassignment in
beforeRetryhooks bf84d36Fix
beforeErrorhook not being called forERR_UNSUPPORTED_PROTOCOLerror fb86418FIx preserving
prefixUrlin hooks 9725fbdFix race condition causing retry after promise settles 1e49781
Fix stream validation errors causing unhandled rejections 2527bf6
Fix incorrect
content-lengthwhen piping decompressed responses 30b3b79Fix EPIPE errors bypassing retry logic in Promise API 6ae3e7f
Fix silent hang when returning cached response with FormData body from beforeRequest hook e09a9bd
Fix hook type definitions to reflect normalized runtime state 6a544a3
Fix
afterResponsehook validation to allownullbody values 60a4419Fix DNS timing being non-zero when connecting to IP addresses 3d66aec
Fix
timings.endbeing undefined when stream is destroyed before completion 4e75679Fix properly treating different UNIX socket paths as different origins e5659d4
Meta
I managed to get it almost down to zero issues! 🎉
14.5.0
10 Oct 2025Add
retry.enforceRetryRulesoption to fix statusCodes/limit bypassing 7c0aee6Add support for
serverNameHTTPS option cdaab63Add
preserveHooksoption forretryWithMergedOptions1abeba4
Add
retry.enforceRetryRulesoption to fix statusCodes/limit bypassing 7c0aee6Add support for
serverNameHTTPS option cdaab63Add
preserveHooksoption forretryWithMergedOptions1abeba4Support
IterableandAsyncIterableas request body b65b0e1Fix hang on revalidated cached responses 2ab94fd
Fix handling of FormData getLength errors a2812de
Fix
downloadProgressfiring for redirect responses 9ec6ff0Fix TypeScript type definition for retry event's createRetryStream parameter e899c07
Fix validation to accept
falseas agent value 6961284Fix HTTP/2 memory leak from timeout listeners with connection reuse d1d4ed2
Fix QuickLRU v7+ compatibility 23d0b6b
Fix it not using HTTP/2 connection reuse by default 724d592
Fix hang with stream requests without body for methods like OPTIONS dc4f1e3
14.3.0
18 May 2024Only updates dependencies, nothing else changes.
- 13.x
13.0.0
27 May 2023- Breaking
Require Node.js 16 52a1063
- Breaking
Change the
enableUnixSocketsoption to befalseby default 852c312
As a reminder, Got continues to require ESM. For TypeScript users, this includes having
"module": "node16", "moduleResolution": "node16"in your tsconfig.Breaking
- Breaking
Require Node.js 16 52a1063
- Breaking
Change the
enableUnixSocketsoption to befalseby default 852c312Most users don't need it.
Improvements
- 12.x
12.2.0
24 Jul 2022Add
enableUnixSocketsoption (#2062) 461b3d4
A whole project to check? Paste its package.json in the dependency check: every deprecated, outdated or vulnerable dependency, with what to upgrade to. Free, no account.