Skip to main content

​
Error codes

When landbase-cli encounters an error, it writes a JSON object to stderr with an error.code field. These codes are stable across versions and are safe to branch on in scripts. 
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please wait before retrying.",
    "meta": { "retry_after_seconds": 30 }
  }
}

​
Code reference

CodeExit codeMeaningWhat to do
AUTH_FAILED3No valid API key or session, or the credentials were rejected.Run landbase-cli auth login. Check LANDBASE_API_KEY in CI.
RATE_LIMITED2Too many requests in a short window.Wait and retry. Check meta.retry_after_seconds if present.
TIMEOUT4The request exceeded the configured timeout.Retry, or increase --timeout. For long workflows, use --wait.
NETWORK_ERROR4A connectivity issue prevented the request from completing.Check your network and retry.
API_ERROR2The Landbase API returned an unexpected error.Check meta for details. If the problem persists, contact support.
DOWNLOAD_FAILED2The file download could not be completed. The publish step may have failed, or the URL may have expired.Re-run the publish workflow and retry.
INVALID_INPUT1The command received invalid arguments or flags.Read message for the specific problem. Fix the command and re-run.
UPGRADE_REQUIRED2The version of landbase-cli you are running is too old to use this API.Run landbase-cli update.
UPDATE_FAILED2The self-update process could not download or install the new binary.Check your network and write permissions in the install directory.
NOT_FOUND2The requested resource (dataset, run, session) does not exist or has been deleted.Verify the ID. Run landbase-cli datasets list to see available datasets.
SETUP_FAILED1A setup or configuration step failed (e.g. config permissions write).Check file system permissions for ~/.claude/ or ~/.codex/.
CONFLICT2A resource conflict prevented the operation (e.g. duplicate upload).Check for an existing dataset with the same name.

​
Capturing error codes in scripts

Capture stderr separately from stdout: 
# Capture stdout to a variable and stderr to a temp file
OUTPUT=$(landbase-cli datasets list 2>/tmp/lb-err.json)
if [ $? -ne 0 ]; then
  CODE=$(cat /tmp/lb-err.json | jq -r .error.code)
  case "$CODE" in
    "AUTH_FAILED") landbase-cli auth login ;;
    "RATE_LIMITED") sleep 30 ;;
    "NETWORK_ERROR") sleep 5 ;;
    *) echo "Unhandled error: $CODE"; exit 1 ;;
  esac
fi