Running Health Checks
crab doctor is the first command to run when something isn't working. It performs a series of diagnostic checks on your installation and repository configuration, reporting exactly what's set up correctly and what needs attention.
What Gets Checked
| Check | What it verifies |
|---|---|
| Git version | Git is installed and meets the minimum version |
| Crab binary | The binary is accessible on PATH |
| Git repository | Current directory is inside a git repo |
| Filter driver | filter.crab.process, .clean, .smudge, .required are configured |
.gitattributes | At least one pattern with filter=crab exists |
| Crab config | .crab/local.toml exists and is parseable |
| Remote URL | crab.toml contains a valid crab URL |
| Remote access | Can reach the bucket and open the repository layout |
| Staging area | .crab/staging/ exists and is accessible |
| Cache | Local cache directory exists |
| Version guard | Repository version is compatible with installed binary |
Reading the Output
Each check produces one of three statuses:
crab doctor ✓ Git version git 2.43.0
✓ Crab binary /usr/local/bin/crab
✓ Git repository /home/user/my-repo
✓ Filter driver filter.crab.process configured
✓ .gitattributes 2 crab patterns found
✓ Crab config .crab/local.toml valid
✓ Remote URL crab://my-bucket/my-repo
✓ Remote access bucket 'my-bucket' and repository 'my-repo' reachable
⚠ Staging area .crab/staging/ (12.3 MB)
✓ Cache ~/.cache/crab (45.6 MB)
✓ Version guard compatible✓— check passed⚠— suboptimal but not blocking✗— critical issue that will prevent Crab from working
Common Issues and Fixes
| Issue | Fix |
|---|---|
| Filter driver not configured | Run crab install or crab init <url> |
| No crab patterns in .gitattributes | Run crab track '*.bin' |
| Remote URL not configured | Run crab init <url> |
| Bucket not found | Create the configured bucket or correct the remote URL |
| Repository not initialized | Run crab configure <REMOTE> to create it |
| Access denied | Grant the active identity the required bucket and repository-prefix permissions, then rerun crab doctor |
| Large staging area warning | Run git push to upload, then crab staging clean |
Typical Workflows
After initial setup
git init
crab init crab://my-bucket/my-repo
crab track '*.bin'
crab doctor # verify everything is wired upBefore filing a bug report
crab doctor --json > doctor-output.json
crab env > env-info.txt
# Attach both to your issueKeep diagnosis and repair separate
crab doctor can probe configuration, credentials, remotes, cache service, and
repository posture, but a passing check does not reconstruct every referenced
file. Use the failed check's remediation for the identified boundary, then run
the same doctor check again. Continue with crab fsck when the symptom involves
missing or corrupt repository objects.
Support bundles and environment output can contain repository URLs, local paths, and provider names even when secrets are redacted. Review the artifacts before sharing them publicly. Keep the Crab version with the output because the set of checks and their remediation can change between releases.
CLI Reference
For complete command syntax and all available flags, see the crab doctor reference.