Inspect errors with errors.Is
value, err := db.Get(ctx, "users", []byte("1024"))
switch {
case errors.Is(err, zeedb.ErrNotFound):
// Handle a missing record.
case err != nil:
return err
default:
fmt.Println(string(value))
}Import errors from the Go standard library. Errors may be wrapped with context; do not compare their text.
Public sentinels
| Error | Meaning | Typical response |
|---|---|---|
ErrNotFound | Missing or deleted record | Treat as absent |
ErrClosed | Handle already closed | Open a new handle |
ErrLocked | Database already open or lock unavailable | Close the other owner; inspect permissions |
ErrLimit | Configured resource budget exceeded | Reduce request size or adjust valid budgets |
ErrInvalid | Invalid collection/key, mutation, range, or options | Correct the input |
ErrCorrupt | Persisted format/checksum/sequence inconsistency or required storage unavailable | Preserve the original files and investigate |
OS I/O errors and context cancellation/deadline errors can also be returned.
At Open, some table failures are wrapped as ErrCorrupt, including an SSTable
that exceeds a newly reduced MaxDataBytes. Inspect the full error chain and
compare the original options before diagnosing physical corruption. The
lifecycle reference describes these current boundaries.
Validation failures
Invalid collections, empty/oversized keys, nonempty delete values, and oversized batches are rejected before WAL append. A failed validation does not partially commit a batch.
Scans return no partial result on byte-budget overflow. Reducing the record limit is the usual first step.
Indeterminate commits
A write or checkpoint I/O failure can occur after some persistent work is complete. A valid complete WAL frame may recover even if the caller did not receive an acknowledgement.
The engine poisons the handle after such a failure and refuses further reads/writes. Close and reopen, then inspect application state before retrying work with non-idempotent effects. There is no embedded operation-ID deduplication yet.
Corruption and incomplete tails
Recovery truncates an incomplete final WAL header/payload to the last complete frame. A complete frame with a bad checksum is rejected instead of silently skipped.
Missing required files, bad headers, malformed records, invalid sequences, and invalid manifests are errors. ZeeDB does not attempt arbitrary file salvage. See durability and recovery before attempting any recovery procedure.
Keep an untouched copy of affected files and exclude credentials or sensitive payloads from bug reports.