mc checksum verify

The mc checksum verify command compares the additional checksum stored by an S3 endpoint with a checksum independently calculated from the logical object bytes returned by that endpoint.

This is a read-only audit command introduced by mcli 20260903. It uses only S3 LIST, HEAD, and GET operations. It never repairs metadata, rewrites an object, or identifies which historical writer produced a mismatch.

The command supports stored FULL_OBJECT CRC32, CRC32C, CRC64NVME, SHA1, and SHA256 checksums. COMPOSITE checksums are reported as unsupported rather than guessed.

When this reference shows mc, use mcli if that is the installed executable name.

Syntax

mc checksum verify [FLAGS] ALIAS/BUCKET/OBJECT
mc checksum verify --recursive [FLAGS] ALIAS/BUCKET[/PREFIX]
mc checksum verify --manifest FILE [FLAGS] ALIAS

Use exactly one selection mode:

• an object path verifies one object;
• --recursive verifies objects under a bucket or prefix;
• --version-id verifies one exact version;
• --versions includes every version selected by an object or recursive scan;
• --manifest reads exact bucket, key, and optional version identities from a JSON Lines file.

For an unversioned object, the command reads with If-Match and performs a second HEAD after the body is consumed. If the object changes during verification, the result is UNKNOWN_OBJECT_CHANGED, not a false mismatch.

Result and exit-status contract

Every candidate produces one stable status:

Normal completion exits 0; a command or selected audit failure exits 1. The default --fail-on any fails on mismatches, UNKNOWN_*, and objects skipped by --max-size.

--fail-on accepts:

• mismatch — fail only on a checksum mismatch;
• unknown — fail on a mismatch or any UNKNOWN_* result;
• no-checksum — also fail when a checksum is absent or the run verified zero objects;
• any — the default, including incomplete size-capped audits;
• none — report findings without turning them into an audit failure.

The final summary contains objects, verified, per-status counts, and incomplete. verified is MATCH + MISMATCH: use it when automation requires proof that at least one checksum was actually recomputed.

Important flags

--limit-download remains available as a global rate limit. Object bodies are streamed through bounded hashers and are neither buffered in full nor written to disk.

Manifest format

Each non-empty line identifies one candidate. bucket and key are required; versionId is optional:

{"bucket":"archive","key":"2025/report.json","versionId":"optional"}

The alias appears once on the command line. The manifest contains neither checksums nor encryption keys.

Examples

Verify one object:

mc checksum verify mysilo/archive/report.json

Estimate the read cost before recursively verifying a prefix:

mc checksum verify --recursive --dry-run mysilo/archive/2025/

Verify all historical versions with four workers and require every selected object to carry a checksum:

mc checksum verify --recursive --versions --max-workers 4 \
  --fail-on no-checksum mysilo/archive/2025/

Verify candidates from an external inventory and keep a private JSON Lines report:

mc checksum verify --manifest candidates.jsonl \
  --report results.jsonl mysilo