Salesforce Dictionary - Free Salesforce GlossarySalesforce Dictionary
All errors
Integration

ChangeDataCapture: missing ChangeEventHeader / cannot replay events

Your Change Data Capture subscriber isn't receiving events, or events are arriving without a `ChangeEventHeader`. Usually means CDC isn't enabled on the object, the subscriber's replay ID is past the 72-hour retention window, or the subscriber is reading the wrong channel.

Also seen asChangeEventHeader·ChangeDataCapture·Cannot replay events·CDC subscription not delivering

Salesforce Change Data Capture (CDC) publishes events when records change — Account, Contact, custom objects you've enabled. Subscribers connect via the Pub/Sub API or CometD and receive the change payload + a ChangeEventHeader describing what happened.

When events don't arrive

1. CDC isn't enabled for the object

Setup → Change Data Capture → check the Selected Entities list. If Account isn't on the right side, no CDC events fire for Account changes regardless of whether your subscriber is listening.

Custom objects appear in the list only after the Track changes option is set on the object's metadata. For custom objects, edit the object → check "Track Field History" or use the explicit "Enable CDC" toggle.

2. Subscription is on the wrong channel

CDC channels are per-object:

/data/AccountChangeEvent
/data/ContactChangeEvent
/data/MyCustomObject__ChangeEvent

Or the catch-all:

/data/ChangeEvents

If you subscribed to /data/AccountChangeEvent but you're updating Contacts, no events arrive. Either subscribe to the right channel or use /data/ChangeEvents to receive all CDC events.

3. Replay ID is stale (past 72 hours)

CDC retains events for 72 hours. If your subscriber goes offline for longer and reconnects with an old replay ID, the platform returns no events for the missing window — and may return an error indicating the replay window expired.

Catch this and replay from the new tip:

client.subscribe('/data/AccountChangeEvent', { replayId: -1 }, callback);
// replayId: -1 = subscribe from now (lose past events)
// replayId: -2 = subscribe from earliest available (up to 72h)
// replayId: <number> = subscribe from after that ID

When events arrive but the header is missing

If the event payload doesn't contain ChangeEventHeader, the subscriber probably parsed the wrong event shape. CDC events have this shape:

{
  "data": {
    "schema": "...",
    "payload": {
      "ChangeEventHeader": {
        "entityName": "Account",
        "changeType": "UPDATE",
        "changedFields": ["Name", "Industry"],
        "recordIds": ["0016xxx"],
        "transactionKey": "..."
      },
      "Name": "New Name",
      "Industry": "Tech"
    },
    "event": { "replayId": 12345 }
  }
}

If you're parsing the platform-event Replay API and treating it as a regular Streaming API event, you may strip the header. Use the official Salesforce Pub/Sub API client.

A subtle case: gap events

CDC sometimes sends a "GAP" event with changeType: "GAP_OVERFLOW" indicating the platform dropped events because the subscriber was too slow. When you see one, replay from replayId: -2 to catch up, or accept the gap and resync from the source.

Pub/Sub API caveat

The newer Pub/Sub API (gRPC) uses a different replay model — replay IDs are bytes, not integers. If you migrate from CometD to Pub/Sub API, your replay-ID handling code needs to update.

Related dictionary terms