Understanding Error Codes

When Crab encounters an error, it prints a structured error code like CRAB-E0017. These codes are stable identifiers you can look up for the meaning, common causes, and suggested fixes — no more guessing from vague error messages.

Looking Up an Error

After encountering an error:

error: non-fast-forward on refs/heads/main [CRAB-E0017]: have abc, want def
help: Run `crab errors CRAB-E0017` for recovery steps.

Setup-related failures also print a direct next action and a relevant docs link. The stable code remains available for scripts and deeper catalog lookup.

Look it up:

crab errors CRAB-E0017

This prints the error name, category, whether it's retryable, and remediation steps.

Browsing All Error Codes

crab errors

Lists every known error code with its name and category. Useful for understanding the error landscape or building monitoring rules.

Error Code Format

Codes follow the pattern CRAB-EXXXX where XXXX is a four-digit number. The lookup is case-insensitive.

Error Categories

Errors fall into categories that tell you how to respond:

Common Error Codes

Machine-Readable Output

For automation and monitoring:

crab errors CRAB-E0017 --json

{
  "schema": "errors",
  "version": "1.0",
  "data": {
    "code": "CRAB-E0017",
    "name": "NonFastForward",
    "category": "conflict",
    "retryable": false,
    "message_template": "non-fast-forward push rejected",
    "remediation": "Pull the latest changes and retry the push."
  }
}

Preserve the original failure context

The catalog explains a stable category, but it cannot include the path, provider response, ref, or operation state from one failure. Record the original command, full error line, exit status, and relevant log before applying the suggested remediation. A retryable category means the condition can be temporary; it does not mean an unbounded retry loop is safe.

For conflicts, reread the current remote state before retrying. For corruption, run a read-only integrity check before --repair. For permission failures, test a read-only operation with the intended identity instead of changing bucket policy until the denied boundary is known.

CLI Reference

For complete command syntax and all available flags, see the crab errors reference.