immediate delivery resolves after failed requests and terminal redirects

[Mnigos]

Bug description

Awaited Node *Immediate() calls resolve after failed HTTP requests, network failures, and timeouts. An error listener sees the failure, but the caller cannot handle it through the returned promise. Separately, core's successful-write response handling accepts terminal 3xx responses as successful writes.

This affects applications that keep events in a durable outbox and acknowledge them only after an awaited send succeeds: an unsuccessful request can cause the application to mark its event processed.

How to reproduce

Reproduced against current main at 910b0925650b83206a191ae7cdca3ce2eb761ede (posthog-node 5.52.1, @posthog/core 1.53.2), Node.js 24.14.1. This uses the supported injected fetch; no live endpoint is needed.

import { PostHog } from 'posthog-node'

for (const status of [200, 302, 503]) {
  const client = new PostHog('test-key', {
    fetch: async () => new Response(null, { status }),
    flushInterval: 0,
    fetchRetryCount: 0,
    disableCompression: true,
  })
  client.on('error', error => console.log('error event:', error.message))
  try {
    await client.captureImmediate({ distinctId: 'repro', event: 'delivery-test' })
    console.log(status, 'resolved')
  } catch (error) {
    console.log(status, 'rejected:', error.message)
  }
  await client.shutdown()
}

Actual: all three resolve; only 503 emits an error. Expected: 200 resolves; terminal 302 and 503 reject. Redirects followed by fetch to a final 2xx remain successful.

Regression tests also reproduce suppressed failures in identifyImmediate, aliasImmediate, groupIdentifyImmediate, captureExceptionImmediate, and captureAiImmediate. Core flush tests reproduce false success for final 300, 302, and 304.

Related sub-libraries

• posthog-node
• Shared transport: @posthog/core

Additional context

PostHogCoreStateless.sendImmediate emits errors without rethrowing; Node _sendPreparedEvent catches and logs without rethrowing. Both layers must preserve the rejection for immediate calls. Normal queued capture should keep its existing background error handling. Required-response reads should retain their current status handling.

This is distinct from the missing-await bug in #3819: the request is awaited here, but its failure is suppressed.

Compatibility needs maintainer review: surfacing immediate transport failures changes observable behavior for callers that relied on suppression. The proposed fix uses existing promises without a new option, method, or exported type; no API-shape agreement is claimed. Intentional skips (disabled client, opt-out, or before_send dropping an event) remain separate from transport acknowledgement. HTTP 2xx does not prove downstream ingestion.

Report and reproduction prepared with GPT-6/Codex at a human contributor's direction.

[github-actions]

AI triage for #4920

Conclusion: Valid Node delivery-semantics bug; the terminal-3xx portion is already fixed in shared core, but immediate calls still suppress transport failures.
Confidence: 97%
Suggested labels: node, team/client-libraries

Thanks for the focused reproduction. The terminal-3xx portion has since been addressed in shared core by #4922: successful writes now require a final 2xx response, while required-response reads retain their existing handling.

The remaining immediate-delivery behavior is confirmed in the current Node source: core's sendImmediate() emits an error event after sendBatch() fails but resolves, and Node's _sendPreparedEvent() has a final catch that logs and resolves. The existing Node regression test explicitly expects 300/302/304/503 immediate writes to resolve after emitting an error.

Changing this needs a deliberate compatibility decision rather than a speculative patch: immediate methods are documented as promises, but callers may currently rely on their suppression behavior. If rejection is adopted, update the focused immediate-delivery tests for HTTP, network, and timeout failures; retain queued/background capture error handling; and exercise shutdown/pending-promise behavior because immediate work is registered in the shared promise queue.

Investigation

• Shared core now rejects successful-write responses with status >= 300; core flush tests explicitly cover 300, 302, and 304 as failures while preserving 302 handling for required feature-flag reads.
• @posthog/core 1.53.3 changelog attributes the final-2xx successful-write change to PR fix(core): reject terminal non-2xx write responses #4922 and explicitly says immediate-call error handling was preserved.
• PostHogCoreStateless.sendImmediate() awaits sendBatch(), emits an error in its catch block, and does not rethrow.
• PostHog._sendPreparedEvent() catches errors from both preparation and sending, logs them, and resolves; this is a second suppression layer for Node immediate methods.
• The existing Node immediate-delivery test currently asserts that HTTP 300, 302, 304, and 503 emit an error without rejecting captureImmediate().
• Immediate work is added to the shared PromiseQueue; shutdown joins that queue and separately catches PostHog fetch errors, so changing rejection propagation requires regression coverage for shutdown rather than only changing the two catches.

Relevant files: packages/core/src/posthog-core-stateless.ts, packages/core/src/__tests__/posthog.flush.spec.ts, packages/core/src/__tests__/posthog.shutdown.spec.ts, packages/core/src/utils/promise-queue.ts, packages/core/CHANGELOG.md, packages/node/src/client.ts, packages/node/src/__tests__/immediate-delivery.spec.ts, packages/node/src/__tests__/posthog-node.spec.ts, packages/node/CHANGELOG.md

Fix assessment

• Straightforward: no
• Risk: medium
• Reason: The code change could be small, but it changes established observable promise behavior and interacts with the pending-work/shutdown path. Maintainer agreement is needed on whether all immediate methods should reject transport failures and on the intended behavior for callers that do not handle those rejections.

Pi session

The resumable JSONL pi session for this run was saved to a private gist: https://gist.github.com/marandaneto/e3dcb761aaf9566e33432d45a1ed1d1f

Download it locally, then fork it into your own pi session:

pi --fork path/to/session.jsonl

Saved session:

• call-1-1-2026-09-14T08-11-55-432Z_01a09ef9-06a8-7c1f-8029-9ea989ccdf20.jsonl

Close proposal

None. No issue close action was taken.

---

Generated by posthog-watcher-action using pi.

[marandaneto]

immediate-error propagation and the shutdown loop and API opt in is open for discussion but not implemented

[Mnigos]

@marandaneto Would a client option such as rejectImmediateOnError: true (default false) work?

It would apply to all six *Immediate methods: transport failures would reject after existing retries, while preserving error events. Default behavior and background capture would remain unchanged.

Shutdown would track non-rejecting completion promises separately from caller-facing promises, including the exception wrapper—without a new shutdown loop or waiting for error response bodies.

Intentional skips (disabled client, opt-out, filtering, duplicate exceptions) would still resolve, so this option would expose transport failures rather than guarantee delivery. Outbox callers would need an explicit policy for skips.

Does this API shape fit your expectations before implementation?