Troubleshooting

Start on Setup if you have never received an event, and on Admissions if events used to arrive and stopped.

No event received at all

The SDK never reached the ingest API. Check, in order:

1. init() runs in server code, before your first request is handled.
2. transport.url points at the exact ingest endpoint shown in Setup and stored as ERRORCORE_INGEST_URL (it must end in /v1/ingest).
3. Outbound network access from the runtime.
4. getHealth(): a rising transportFailures with a lastFailureReason tells you it tried and failed; captured at zero tells you nothing was captured in the first place.

If droppedBreakdown.deduplicated is rising, your test error is being suppressed by the roughly 10-second fingerprint window. Wait, or vary the error.

Event rejected

The envelope reached errorcore and was not accepted. Rejections that pass authentication are recorded in Admissions with a fixed reason string; earlier failures are plain HTTP errors.

plan limit reached (code plan_limit)

The organization's allowance for this period is used up. HTTP 403. No allowance was consumed and retrying cannot succeed; upgrade the plan or wait for the period to reset. Open Settings → Billing. See billing and usage.

This is not throttling. Do not add backoff for it.

rate limited

Requests arrived faster than the ingest limiter allows. HTTP 429 with Retry-After. No allowance was consumed and nothing was persisted. The SDK already retries with jitter; if this is constant, reduce capture volume or contact support about the limit.

malformed envelope

The envelope failed shape validation, or its keyId did not resolve to an active project key. Check:

• The SDK version is current and emitting envelope v2.
• ERRORCORE_DEK on the sending server matches an active or overlapping key in Settings → Encryption.
• The key was not retired mid-deploy.

An HMAC verification failure returns 403 and is counted as an unauthorized envelope; it consumes no allowance.

Authentication failed (401)

The key sent as ERRORCORE_API_KEY was missing, unknown, revoked, or past its rotation grace. A 401 never creates an admission record, so nothing appears in Admissions. Scope also comes only from the key; sending to the "wrong project" is really the wrong key deployed. Confirm the value on the sending server, then rotate it in Settings → API keys if you cannot account for it.

Repeated authentication failures from one source are throttled with 429 responses; this protects against credential probing and clears on its own.

body too large

The envelope exceeded the configured body cap (413). Reduce body capture, tighten scrubbing, or lower serialization.maxPayloadSize.

Duplicate or conflicting submissions

Repeating an event id with identical content replays the original receipt (202, duplicate: true) and consumes no allowance. Repeating an event id with different content returns 409; that means two different errors were assigned the same id, which is a bug in custom capture code.

Accepted but no case appears

202 means durably admitted, not reconstructed. Check Jobs for the reconstruct job, then DLQ. A job that failed at decrypt, parse, or scrub is quarantined rather than silently dropped.

Worker not processing

Open Workers and Jobs: heartbeat freshness, queue depth, attempts, and last error.

Source maps missing

Confirm source maps are available server-side in the deployed artifact and that resolveSourceMaps is enabled.

Next.js: initialization in the wrong place

Initialize from instrumentation.ts using errorcore/nextjs, and wrap route handlers with withErrorcore(). Keep both secrets out of client components; the edge runtime resolves to a no-op stub by design.

Local development

Use transport: { type: 'stdout' } or a file transport to confirm capture without sending anything. See local development.