Diagnose and repair a repository

Start with the narrowest command that identifies the failing boundary. Preserve logs and structured output before applying repair, recovery, or destructive maintenance.

Capture the first useful evidence

Run health and integrity checks without changing repository state:

crab doctor
crab fsck
crab logs last

Keep the first error code and the command that produced it. Repeated retries can replace useful context with secondary failures.

Use JSON when automation or a support bundle needs stable fields:

crab doctor --json > doctor.json
crab fsck --json > fsck.json

Choose the tool from the failing boundary

Repair only after classification

crab fsck --repair is not a substitute for diagnosis. Review the dry result first, confirm that the command targets the intended repository, and retain its output.

After any repair, rerun the original check and hydrate a representative file from an isolated client. A clean metadata report alone does not prove that remote bytes reconstruct correctly.

Prefer a new clone or an empty cache for this final hydration so local cached chunks cannot hide a missing remote object.

Preserve an incident record

Record these artifacts together:

• The first failing command and exit code
• Crab version and operating system from crab version --json
• crab doctor --json output with secrets excluded
• Integrity or recovery output used to approve the action
• The repair command and its terminal result
• The verification command and a representative hydration result

Continue with the identified boundary

• Inspect command logs
• Verify remote storage
• Recover interrupted operations
• Check installed version information