event-hash-version-unknown

• Routes: restore-backup and audit-history
• Descriptions: event hash version is unknown: the backup was written by a newer release, which is needed to restore it when restoring a backup, and event hash version is unknown: the event was written by a newer release, which is needed to audit it when auditing the event store
• Details: eventId, the ID of the event.

Why It Happens#

A restore checks the chain of hashes of the backup, event by event, and computes the hash of each event again to compare it with the one the event holds. The hash of an event names its version in a prefix: esdb:hash:v2: for version 2, which this version writes, and no prefix for version 1. A hash whose prefix names another version comes from a newer version of EventSourcingDB, and this version cannot compute it.

An audit checks the chain of the stored events the same way and refuses such an event as well. It meets one only in a store that came by it otherwise, since EventSourcingDB refuses to start on a data directory that a newer version has written.

Rather than take such an event for one that was changed, which event-chain-broken reports, EventSourcingDB names the version of the hash as the reason. An older version can restore a backup only as long as it can read everything the backup contains, see Compatibility.

How to Fix It#

Restore the backup with the version of EventSourcingDB that created it, or a newer one. EventSourcingDB has removed what it restored so far, so the database is empty again. Audit a store that holds such an event with the version that wrote it, or a newer one. Resending the request to this version fails the same way.

Example#

For a backup whose event 0 has a hash of a version that this version does not know, 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-hash-version-unknown",
    "description": "event hash version is unknown: the backup was written by a newer release, which is needed to restore it",
    "details": {
      "eventId": "0"
    }
  }
}