Error codes¶

shard-db errors are JSON objects with a machine-readable error field. Most include contextual fields (current, filename, etc.) to help clients recover.

Error response shape¶

{"error":"<code>", "...context fields..."}

Clients should match on the error string, not on the full message.

Common errors¶

Infrastructure¶

`error`	Cause	Recovery
`Cannot connect to port N`	Server not running or wrong port.	Check `./shard-db status`, verify `PORT` in `db.env`.
`Server shutting down`	Sent during graceful stop while draining.	Retry against the new instance or wait for restart.
`Request too large (max N bytes)`	JSON request exceeded `MAX_REQUEST_SIZE`.	Split into smaller requests, or raise `MAX_REQUEST_SIZE`.
`query_timeout`	Query exceeded `TIMEOUT` (db.env) or per-request `timeout_ms`.	Add filters, add an index, raise the timeout.
`query memory buffer exceeded; narrow criteria, add limit/offset, or stream via fetch+cursor`	Query intermediate buffers crossed `QUERY_BUFFER_MB`.	Narrow `criteria`, add `limit`, or stream via `fetch` + cursor.
`durability outcome pending; do not retry blindly`	The server durably published an indexed mutation marker but could not synchronously converge it.	Do not retry the mutation. The retained marker blocks later writes on that shard until synchronous replay or startup recovery completes.

Validation¶

`error`	Cause	Recovery
`Unknown dir: <name>`	`dir` not in `dirs.conf`.	Register the dir or fix the typo.
`Object [<name>] not found. Use create-object first.`	Querying an object that doesn't exist.	Create it via `create-object`.
`Missing criteria`	`find` without a `criteria` field.	Pass `"criteria":[]` for all-records.
`fields is required`	`create-object` without `fields`.	Provide at least one field spec.
`fields array is empty`	Empty `fields` array in `create-object` or batch ops.	Provide at least one element.
`invalid field type: "<spec>"`	Unknown type or malformed size.	Check spelling; see Typed records.
`invalid field name (no :, +, /, spaces)`	Reserved character in field name.	Use `[a-zA-Z0-9_-]`.
`Invalid field name: <name>`	Same, from `remove-field`.	Fix the name.
`max_key N exceeds ceiling 1024`	`create-object` with a too-large `max_key`.	Use ≤ 1024 (UUIDs fit in 36B).
`too many fields (max 256)`	Schema exceeded `MAX_FIELDS`.	Consolidate or drop unused fields.

File storage¶

`error`	Cause	Recovery
`invalid filename`	Filename contained `/`, `\`, `..`, control chars, or was empty / too long.	Use a plain basename ≤ 255 bytes.
`missing data`	`put-file` without `data` or `path`.	Provide one.
`filename is required when uploading via data`	base64 put-file with no `filename`.	Add it.
`filename is required`	`get-file` without filename.	Add it.
`file not found`	`get-file` on non-existent file.	Check filename (case-sensitive).
`file exists`	`put-file` with `if_not_exists:true` hit an existing file.	Pick a new name or omit `if_not_exists`.
`invalid base64`	Malformed `data` payload.	Validate encoder; whitespace is tolerated but invalid chars aren't.
`cannot create <path>`	Server-side I/O error writing tmp file.	Check disk space, permissions.
`write failed`	Short write to file descriptor.	Usually disk-full.
`rename failed`	Atomic rename step failed.	Check filesystem consistency.
`read failed`	Short read from stored file.	Indicates corruption — restore from backup.

Conditional writes / CAS¶

`error`	Cause	Recovery
`condition_not_met`	`if_not_exists` or `if:[...]` check failed. Response includes `"current"` with the actual record.	Inspect `current`, reconcile, retry.
`key already exists`	`insert` without `if_not_exists` when the key was just written by a concurrent request (rare race).	Use `if_not_exists:true` for idempotent inserts.

Index management¶

`error`	Cause	Recovery
`field is required`	`remove-index` with neither `field` nor `fields`.	Add one.
`fields must be a JSON array`	`fields` wasn't an array.	Pass `["a","b"]`.

The remove-index response {"status":"not_indexed","field":"x"} is not an error — it's the idempotent-no-op response when the field wasn't indexed.

Bulk operations¶

`error`	Cause	Recovery
`some_records_dropped`	`bulk-insert` rejected some records (type mismatch, missing required). Response includes `errors` count.	Check logs for detail; re-submit rejected rows.
`Missing criteria or value`	`bulk-update` without both.	Provide both.

Auth¶

`error`	Cause	Recovery
`auth failed`	No matching token, IP not allowlisted, or token's scope/perm doesn't cover the request.	Check token scope (`global`/tenant/object), permission (`r`/`rw`/`rwx`), and the request's `dir`/`object`.
`object scope requires dir`	`add-token` with `object` but no `dir`.	Provide both.
`invalid perm: must be r, rw, or rwx`	`add-token` with an unrecognized perm.	Use `r`, `rw`, or `rwx`.
`object not found: <dir>/<obj>`	`add-token` referencing a non-existent object.	Create the object first.
`invalid dir name (no /,\\,..,control chars; max 64 bytes)`	`add-dir` with an unsafe name.	Use `[a-zA-Z0-9_-]`, ≤ 64 bytes.
`dir is not empty — drop objects first or pass check_empty:false`	`remove-dir` while objects still live under the tenant.	Truncate/remove objects, or pass `check_empty:false`.

Non-error status values¶

Some responses look error-ish but are normal:

{"status":"not_found","key":"..."} — delete on a missing key. Not an error; your delete is a no-op.
{"status":"not_indexed","field":"..."} — remove-index on a non-existent index. Idempotent no-op.
{"status":"exists","field":"..."} — add-index without force:true on an already-indexed field.
{"count":0} — a count/find with no matches. Normal.

Debugging¶

Check the error string verbatim — they're stable across versions.
Check error-YYYY-MM-DD.log in $LOG_DIR for the server-side context.
For mysterious hangs — ./shard-db stats shows in-flight writes and active threads.
For slow queries — slow-YYYY-MM-DD.log + the in-memory ring via stats.
For suspected corruption — stop the server, run vacuum-check, back up before any repair attempts.