Repository navigation
posthog-node@6.0.0
6.0.0
Major Changes
-
#5407
6405dfdThanks @eli-r-ph! - RemoveenterContext(); usewithContext()to scope async context to a callback.
(2026-11-17) -
#5407
6405dfdThanks @eli-r-ph! - Use camelCase SDK configuration names and typed boolean event options with support for additional JSON-valued options.
(2026-11-17) -
#5407
6405dfdThanks @eli-r-ph! -captureException()andcaptureExceptionImmediate()take an options object (distinctId,properties,options,uuid,flags,level). The old positional form still works in posthog-node 6.x.x and logs a deprecation error once per method.levelis read case-insensitively, with the same aliases as posthog-python (critical→fatal,warn→warning). An unknown level keepserror.
registerOptions()andunregisterOptions()return a promise, andprepareEventMessage()returns a flat message with top-leveloptions,uuid,timestampanddisableGeoip. (2026-11-17) -
#5407
6405dfdThanks @eli-r-ph! - Generated event uuids and personless distinct ids take their random bits fromcrypto.getRandomValuesinstead ofMath.random.
(2026-11-17) -
#5407
6405dfdThanks @eli-r-ph! - A personal API key (phx_...) passed as the project API key now disables the client, like a missing key, and either case logs one error that never includes the key.
Debug mode logs event names, uuids and counts instead of whole events, and abefore_sendfunction that throws is logged with the error's type instead of its message. In debug mode, a capture error can still include the server or proxy response text.
A new client option,captureTracingHeaders(defaulttrue), controls whether the Express and NestJS integrations read theX-POSTHOG-DISTINCT-IDandX-POSTHOG-SESSION-IDrequest headers into the request context. (2026-11-17) -
#5407
6405dfdThanks @eli-r-ph! - Analytics and AI events are batched and sent on separate lanes, in batches of about 5 MiB at most, and events that fail with a network error are kept and retried on the next flush.flush()no longer rejects on delivery failures (they arrive through the'error'event), andmaxQueueSizenow applies to analytics events only.
(2026-11-17) -
#5407
6405dfdThanks @eli-r-ph! - Values set on the event, in context or withregister()/ the newregisterOptions()now win over the values the SDK adds ($is_server,$geoip_disable, feature flag properties, trace ids), andbefore_sendsees and can change all of them. Context and registered properties and options, including the new contextoptions, also reach identify, alias and group identify events, but they do not setprocess_person_profileon$identify,$create_alias,$merge_dangerously,$groupidentify,$setor$set_onceevents whose distinct id the SDK did not generate, which default totrueunless the call sets it.
An empty or whitespace distinct id counts as missing, and$groupidentifywithout a distinct id uses the context id, then$<type>_<key>.
$geoip_disableand$groupsare filled beforebefore_send, so a hook that changes the message'sdisableGeoiporgroupsfield has no effect: edit the properties instead.
Reserved exception properties such as$exception_levelpassed incaptureException()properties are now ignored, so the SDK's value is sent. (2026-11-17) -
#5407
6405dfdThanks @eli-r-ph! - Every capture call takes a per-eventoptionsmap that is sent to capture unchanged (the SDK no longer converts option values). Legacy option properties still work, but an option overrides its legacy property. Use options.
A$session_idor$window_idthat is not a string is dropped with a warning.
Capture drops an event whose option value it cannot read, such ascookieless_mode: [1, 2, 3], and the SDK reports it through'error'withdetails: 'invalid_options'. (2026-11-17) -
#5407
6405dfdThanks @eli-r-ph! - Events send$liband$lib_versionin their properties: a$libset on the event, in context or withregister()wins over the SDK's own pair, andbefore_sendcan change or remove them.
(2026-11-17) -
#5407
6405dfdThanks @eli-r-ph! - Capture follows only same-origin 307 and 308 redirects. Invalid event uuids are replaced with a warning, and dropped duplicate copies are reported.
(2026-11-17) -
#5407
6405dfdThanks @eli-r-ph! - Capture retries only 404, 408, 429, 500, 502, 503, 504 and network errors, waiting 100 ms doubled per retry with jitter (at most 30 s, at leastRetry-After).
AddscaptureMaxRetries,captureCompression,captureAiCompression,captureAiMaxQueueSizeandcaptureAiRequestTimeoutMs. (2026-11-17) -
#5407
6405dfdThanks @eli-r-ph! - Capture always uses capture v1:POSTHOG_CAPTURE_MODEis no longer read,captureAisends to/i/v1/ai/events, andCaptureV1Erroris nowCaptureError.
(2026-11-17) -
#5407
6405dfdThanks @eli-r-ph! - Send events only through capture v1, with AI events on their own lane. See the posthog-node 6.0.0 migration guide.
(2026-11-17) -
#5407
6405dfdThanks @eli-r-ph! - An event whose name is missing, empty or not a string, or whose name, distinct id, session id or window id is not well-formed Unicode (a lone surrogate), is dropped before sending and reported through the'error'event, instead of being sent and failing at capture (an object name was sent as"[object Object]"). Lone surrogates in property strings are replaced with U+FFFD, so one bad character no longer fails the whole request.
An unparseable event timestamp is still replaced with the current time, and now logs a warning that never includes the value. (2026-11-17)
Patch Changes
-
#5407
6405dfdThanks @eli-r-ph! - Export the table of per-event options and the event properties posthog-node 5.x.x reads instead, so posthog-node,@posthog/aiand@posthog/mcpshare one copy.
(2026-11-17) -
#5407
6405dfdThanks @eli-r-ph! - A 2xx capture response whose JSON body has noresultsfield now fails the whole batch and reports it through the'error'event, like a body that is not JSON or has aresultsvalue that is not an object. The batch is not resent. A response with an emptyresultsobject still means every event was delivered.
(2026-11-17) -
#5407
6405dfdThanks @eli-r-ph! - An event whosebefore_sendhook leavesdistinctIdmissing,nullor not a string is now dropped before sending and reported through the'error'event as a local drop (details: 'invalid event'). Before, the SDK sent the value as text, or sent""when the hook removed it. A caller's non-stringdistinctIdis now turned into a string beforebefore_sendruns, so a hook that leaves it alone still sends it. A hook that setsdistinctIdto""still sends it, and capture drops that event and reports it.
(2026-11-17) -
#5407
6405dfdThanks @eli-r-ph! - Abefore_sendhook that throws is now logged withconsole.erroreven whendebugis off, so the dropped event is never silent. The line still names only the event and the error's type.
(2026-11-17) -
#5407
6405dfdThanks @eli-r-ph! - An event with a property value that throws when the SDK reads or serializes it, such as a getter or atoJSONmethod that throws, is now dropped alone and reported through the'error'event as a local drop (details: 'unserializable event'). This covers the call's properties, the copy made forbefore_send, and serialization, on the analytics and AI lanes. In posthog-node 5.x.x, a value that threw while the client read the call's properties printed the raw error withconsole.error, and one that threw during serialization failed the whole batch and emitted the raw error on'error'. With no'error'listener, the SDK logs one line with the count and reason only.
(2026-11-17) -
Updated dependencies [
6405dfd,6405dfd,6405dfd,6405dfd]:- @posthog/core@1.69.0