Start with the failure boundary
Record the engine revision, Go/OS version, filesystem, original options, operation, error chain, and whether the application received a durable acknowledgement. Preserve affected files before experimenting. Avoid logging sensitive values or credentials.
Database already open
ErrLocked means the process lock could not be acquired. A second handle in the same process, another application, or the CLI may be the owner. Permissions and filesystem lock support can also make it unavailable.
Share one existing handle or close the owner. A process crash releases the OS lock; a persistent LOCK filename alone does not imply stale ownership. Do not delete LOCK to bypass a live owner.
Existing data will not reopen
Compare the original options and engine version first. The CLI uses defaults and may reject data created with larger custom budgets. Open checks WAL size, recovered record size, table data size, and format metadata.
Some table-open errors, including a table exceeding configured MaxDataBytes, are currently wrapped as ErrCorrupt rather than ErrLimit. A corruption sentinel does not eliminate the need to inspect the full error and original configuration.
Missing CURRENT/WAL/table files, bad checksums, and malformed sequences are not repaired by creating empty replacements. Do not delete files until a valid recovery/restore plan exists.
ErrLimit on a small write
A mutation must fit several budgets at once: key, value, batch payload, operation count, final live data, and final distinct memtable state. Collection/key metadata and framing contribute to some limits even if the visible value is small.
Repeated keys count individually toward encoded batch size. A delete frees live data but still needs a tombstone. Inspect the configuration table and WriteBatch formula.
ErrLimit on Scan
Lower Limit and retry from the same start; errors return no partial page. A limit above MaxScanRecords is also rejected. A single record can exceed a small MaxScanBytes budget; reducing the count cannot solve that case.
Keys look out of order
Ordering is byte-lexicographic. 10 sorts before 2. Use a fixed-width sortable encoding when numerical order matters. Mixed encodings and inconsistent separators can produce surprising range boundaries.
For pagination, do not reuse the last key inclusively. For prefix ranges, do not assume prefix + 0xff is a universal end. See the ordered-key recipe.
Writes succeeded but another call saw a different state
Different calls can observe different commits. Only one lookup/scan or one mutation batch defines its own visibility boundary. A version is not CAS; a read-modify-write sequence can lose updates without application coordination.
A write errored; can it have committed?
Yes, if an I/O failure happened after append/publication began. A complete unacknowledged frame may recover. The handle is poisoned after write/checkpoint I/O failure; close/reopen and inspect state before retrying non-idempotent application work.
A deadline cannot undo persistent append or checkpoint work. Do not assume cancellation or an acknowledgement failure is proof of rollback.
Reads are slow during writes
Automatic checkpointing merges the entire table under the exclusive lock. Concurrent reads wait. Scan limits and startup checksum verification also affect latency. The engine does not have background leveled compaction or a block cache yet.
Measure table size, workload, batch shape, durability mode, and whether the slow calls coincided with checkpointing before changing buffers.
CLI output looks encoded or lacks a newline
get writes raw bytes without a newline. scan and batch JSON use base64 byte fields through Go’s JSON encoding. --base64 changes input flags, not the scan output format. This behavior is intentional.
Close returned an error
Preserve and inspect the first close error. A later idempotent close returning nil does not prove the earlier sync succeeded. Check filesystem capacity, permissions, and device errors, and validate a working recovery copy when needed.
Report a reproducible issue
Use GitHub Issues with a minimal program and explicit options. Describe whether you used a copied directory, a process kill, relaxed mode, or tighter reopen limits. Exclude private data and credentials.