file-unreadable

• Routes: read-events, observe-events, read-subjects, read-event-types, read-event-type, run-eventql-query, audit-history, create-backup, export-events, restore-backup, import-events, register-event-schema, and write-events for a file whose content is damaged; verify-store for a file that the operating system fails to read
• Description: file is unreadable: '<file>' is damaged: <check>, with the path of the file in the data directory and the check it failed, such as file checksum does not match; from verify-store, file is unreadable: '<file>' could not be read, so the store was not verified: <error>, with the error of the operating system
• Details: file, the path of the file in the data directory, with forward slashes.

Why It Happens#

Every file of the store carries checks of its format: a signature, a version, and a checksum over its content. When the bytes of a file change outside EventSourcingDB, for example through a fault of the disk, an edit by hand, or tampering, the file fails these checks, and a route that needs it reports this error in place of its answer: as the response itself, or as an item of its stream, after which the stream ends. The server logs it as well. A file whose version the release does not know counts as damaged too, since EventSourcingDB refuses to start on a data directory that a newer release wrote.

An export answers with this error as a single envelope, with the content type application/json, where it meets the file before its first event, since an export carries no error items, and cuts its connection where it meets it after that.

An import reports this error as well for the damaged schema file of the type of an event that it imports, which was registered before the import, and leaves the file as it is when it removes what it imported so far.

Some files are read once and then held in memory, so damage that happens while the server runs may show only in a verification, or after a restart.

A verification reports a damaged file as a finding, together with everything else it finds. It reports this error only when the operating system fails to read a file, for example with an input/output error of a failing disk or for lack of permission: the verification then stops there and sends no findings, since what it would find beyond is no result.

How to Fix It#

For a damaged file, verify the store to see what else is damaged, and restore the latest backup into an empty data directory. Do not repair the file by hand: its checksum guards its content, and the chain of hashes guards the events.

For a file that the operating system fails to read, check the file and the disk it lies on, and verify again once the operating system can read the file. If the failure has passed, such as a disk that returned input/output errors for a few seconds, the next verification can succeed right away.

Examples#

For reading the events of /books/42 from a store whose events file events/0.esdb was changed on disk, 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/file-unreadable",
    "description": "file is unreadable: 'events/0.esdb' is damaged: file checksum does not match",
    "details": {
      "file": "events/0.esdb"
    }
  }
}

For a verification during which the disk fails to read the events file events/1.esdb, 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/file-unreadable",
    "description": "file is unreadable: 'events/1.esdb' could not be read, so the store was not verified: input/output error",
    "details": {
      "file": "events/1.esdb"
    }
  }
}