backup-malformed

• Route: restore-backup
• Description: backup is malformed: <reason>, with the reason: for an item out of place, expected a backup item to begin a part, but got one of type '<type>', expected the end item of a part before the next part, or expected the schemas of a part before its events; for an item of a type that a backup does not hold, expected an item of a backup, but got one of type '<type>', or unknown backup item type in a backup that the v1 API created; for a schema that is not a JSON object, expected a schema that is a JSON object; for a value of an event or a schema that is missing or malformed, a text that names the value, for example subject is missing: expected a slash-separated path such as '/books/42'; for a line that is longer than any item of a backup can be, line <line> is longer than any item of a backup can be, which is at most 615424 bytes; for a schema that takes more as a backup writes it than any schema of a backup can, the schema of event type '<type>' is longer than any schema of a backup can be, which is at most 614400 bytes; and for a line that is not JSON in the shape of an item, the message of the JSON decoder, such as unexpected end of JSON input
• Details: line, the number of the line in the request body, counting from 1, heartbeats included.

Why It Happens#

A restore reads the backup line by line, checks that each line is an item that a backup holds at its place, and stops at the first line that is not. In a backup that the v2 API created, each part begins with a backup item and ends with an end item, with its eventSchema items before its event items. A backup that the v1 API created holds schema, event, and error lines, each with a payload. In both formats, the schemas come before the events: a schema after an event is refused with expected the schemas of a part before its events, whichever API created the backup. Each event is also checked value by value, as writing events checks it, so an event without a subject is refused here, too. Every key of a line is read exactly as it is documented: a key spelled otherwise, such as Type or TYPE, is one that the line does not have, so a backup spelled that way throughout begins with an item without a type, and is refused with expected a backup item to begin a part, but got one of type ''.

A restore also bounds each line, to 601 KiB, its newline aside, which is more than any item of a backup takes, and refuses a longer one without reading it to its end, so that a single line cannot take up the memory of the server. A schema takes at most 600 KiB as a backup writes it, six times the body that registering a schema accepts, since a backup writes each <, >, and & in a string as an escape of six bytes. A restore takes a schema as the backup holds it, though, and a backup made by hand may hold one far shorter than the next backup writes it, so the restore refuses a schema that takes more as a backup writes it: the backups of the store that took it could not be restored otherwise. See Limits.

Typical causes are a backup that was changed by hand, or written by another tool with its keys spelled otherwise than documented, a line that was cut, and an empty line, as when two files are joined with an empty line between them. An event whose values are valid, but which does not follow on the one before it, is reported as event-chain-broken instead.

How to Fix It#

Remove or repair the line that line names, or create the backup again, and send each part exactly as creating it sent it. EventSourcingDB has removed what it restored so far, so the database is empty again. Resending the request unchanged fails the same way.

Example#

For a backup whose seventh line is empty, because two files were joined with an empty line between them, 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/backup-malformed",
    "description": "backup is malformed: unexpected end of JSON input",
    "details": {
      "line": 7
    }
  }
}