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: CRAB-E0017: failed to acquire push lock

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."
  }
}

CLI Reference

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