Errors and help

Every refusal from LakehouseBox says what went wrong and what to do next. This page explains how to read one, lists the errors people and agents meet most and what each one wants, and says where to look when something seems broken. Every error code a public route can answer is in the index at the end.

How an error looks

The API answers every failure with one JSON object:

{"error": {
  "code": "quota_exceeded",
  "message": "This organisation is over its private storage limit: 5,400,000,000 of 5,368,709,120 bytes.",
  "limit_value": 5368709120, "current": 5400000000, "headroom": 0,
  "remedy": "… what frees space, or who raises the limit",
  "request_id": "…"}}

• code is stable: match on it, never on message.
• remedy, when present, is the next step. Act on it rather than retrying the same request.
• request_id is always there. Quote it when you write to us.
• Some errors add fields that help: field (which input was wrong), limit, current and available (a limit and where you stand), retry_after_seconds (when to try again, also sent as Retry-After), attempts_left, candidates (the ids behind an ambiguous name), can_grant (who can give you access).
• An unexpected failure is a 500 with the same shape and a request_id.

When the caller is an lhbox older than the one published, a refusal also carries cli_outdated with the published version and how to update: an option the docs describe may be newer than your CLI. lhbox update installs the current one.

The lhbox CLI prints the same object (on stderr) and ends with an exit code that says what kind of failure it was:

The errors you will meet most

Two refusals come from your engine rather than from the API:

• A commit conflict (409 from the catalog, CommitFailedException in PyIceberg and Spark). Iceberg commits are optimistic: when someone else committed to the table first, including the catalog's own maintenance, your commit is refused and should be retried on the new version. Spark retries a few times on its own; a script that writes with PyIceberg should catch the conflict and retry.
• DuckDB: "attached in read-only mode". The catalog was attached with s3://<bucket>/ instead of the bare bucket name. lhbox duckdb and lhbox connect --engine duckdb print the right ATTACH. More gotchas per engine: Engines.

Before you write to us

1. lhbox doctor checks this machine end to end: the key, the catalog, the engine recipe (--write-probe also writes and deletes one empty file, the one check that sees a refused write).
2. lhbox whoami says which key and organisation are in use; lhbox usage lists every limit with your headroom.
3. lhbox update when the CLI says it is out of date.
4. The status page shows whether signing up, logging in, connecting an agent, reading and writing data, the MCP server and the website work right now, checked every 5 minutes from outside our servers.

Getting help

Write to hello@lakehousebox.com with the command or request, the request_id and what you expected. The first answer comes within 2 business days on every plan, within 1 business day on Enterprise (support). Security reports go to the same address (security.txt).

Every error code

Built from the API reference: each code a public route documents, its HTTP status and the routes that answer it (what each means on that route is there).