event-too-large

• Routes: write-events, restore-backup, and import-events
• Description: /events/<index>: event is too large: it may take at most 64 KiB, including its hash when writing events, with the place of the event in its list, counting from 0, and event is too large: it may take at most 64 KiB, including its hash when restoring a backup or importing events
• Details: When writing events, event, the place of the event in its list, counting from 0. When restoring a backup or importing events, eventId, the ID of the event.

Why It Happens#

A single event may take at most 64 KiB, measured as the database stores it: its data together with its other fields, such as its source, subject, and type, the fields that the database adds, such as its ID, its time, and the hash of its predecessor, and its own hash, see Limits. So the data of an event has to stay somewhat below 64 KiB. A typical cause is a large document in the data of an event, such as the full text of a book or an image encoded as Base64.

When writing events, the size is checked once the preconditions hold, event by event, and before an event is checked against the schema of its type, so that an event that is too large is never validated. A write with such an event is therefore refused with this error even where that event, or one after it, does not match its schema, or has a type without a schema while schemas are required, and none of the events is written. When restoring a backup, the restore fails at the event, and the database removes what it has restored so far, see When a Restore Fails. When importing events, the import fails at the event, and the database removes what it has imported so far, and keeps the schemas that were registered before it. An import computes the hash of each event itself, and the size counts it as well.

How to Fix It#

Keep each event small: store large content elsewhere, such as in a blob store, and put a reference to it into the event. Sending the same request again fails the same way, and so does restoring the same backup or importing the same events.

Example#

For a write whose first event holds the full text of a book in its data, 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-too-large",
    "description": "/events/0: event is too large: it may take at most 64 KiB, including its hash",
    "details": {
      "event": 0
    }
  }
}