event-chain-broken

• Routes: restore-backup, import-events, and audit-history
• Descriptions: event chain is broken: an event does not name the hash of the one before it, when its predecessor hash is not the hash of the event before it; event chain is broken: an event does not follow on the ID of the one before it, when its ID is not the next one; event chain is broken: an event is older than the one before it, when its time lies before that of the event before it; and event chain is broken: an event does not match its hash, when its hash is not the one computed from the event
• Details: eventId, the ID of the event at which the chain breaks.

Why It Happens#

Every event names the hash of the event before it as its predecessor hash, and carries a hash of its own, so the events form a chain. An audit checks that chain from the first event on, and a restore checks the events of the backup as it takes them. Both stop at the first event that breaks the chain, and check each event in the order of the descriptions above, so the description names the first problem of that event.

For an audit, this means that the stored events were changed or damaged; for a restore, that the backup was. An import computes the hashes itself, so its events break the chain only by their IDs or their times: an ID that does not follow on the one before it, as where the first event is not 0, a line went missing, or a line is there twice, or a time earlier than that of the event before it. An import that fails this way removes what it has imported so far, and keeps the schemas that were registered before it. A restore that fails this way removes what it has restored so far, so the database is empty again. An event of the backup whose hash has a version that this version does not know is reported as event-hash-version-unknown instead, and verifying the store reports a broken chain as a finding rather than as this error.

How to Fix It#

Sending the same request again fails the same way, since the events themselves are at fault. After a failed audit, investigate the database, starting with a verification of the store, which reports what else it finds; after a failed restore, restore a backup that is intact; after a failed import, number the events from 0 on without gaps, and keep their times from falling.

Example#

For an audit of a database whose event 17 was changed after it was written, EventSourcingDB answers with this error, as a line of the stream, and then ends the stream with its end item:

{
  "type": "error",
  "data": {
    "code": "https://docs.eventsourcingdb.io/errors/event-chain-broken",
    "description": "event chain is broken: an event does not match its hash",
    "details": {
      "eventId": "17"
    }
  }
}