Pitfalls and danger zones

Places in the codebase where mistakes are common or the consequences are unusually large.

Don't bypass namespace-lock

Every ObjectLayer mutating call must acquire a lock first. Skipping it because "this is a quick read-modify-write" is the leading cause of subtle replication and metadata bugs. Use objectAPI.NewNSLock(bucket, object).

Don't reach past the ObjectLayer interface

Calling xl-storage directly works locally but breaks in distributed deployments where the drive may be on another node. Always go through the interface.

xl.meta schema changes need a migration

Bumping the version field in cmd/xl-storage-format-v2.go requires a matching migration in cmd/xl-storage-format-v2-legacy.go and a regression test that exercises the upgrade path. Skipping the migration leaves customers unable to upgrade without re-uploading data.

Don't hand-edit *_gen.go or *_string.go

Regenerate with go generate ./.... CI fails if the regen produces a diff (Makefile:check-gen).

Streaming SigV4 chunk parsing is a hot zone

cmd/streaming-signature-v4.go is one of the most-bug-fixed files in the repo. Chunk-extension handling, trailer parsing, and SHA-256 progressive computation interact in ways that are easy to break. New code paths must add tests for malformed inputs.

cmd/api-errors.go is the only place to add error codes

Adding an error code anywhere else won't get a string table entry, an HTTP status mapping, or a slot in the AWS-compatible error envelope. Always extend the enum + run go generate.

Lock force-unlock is dangerous

mc admin lock force-unlock (and the matching admin endpoint) bypasses DSync. If the original holder is still alive it can corrupt xl.meta. Only use after confirming the holder is gone.

cmd/globals.go is one big global state bag

Every singleton (object layer, IAM system, peer REST, lockers, KMS, ...) lives there. Adding a new global is the path of least resistance but accumulates over time. Prefer threading dependencies explicitly when you can.

Multipart upload ETag math

The multipart ETag (internal/etag/etag.go) is MD5(MD5(part1)|...)-N. Clients verify it. Don't change the algorithm without coordinating with minio-go and mc.

Free versions can mask data loss

A "deleted" version is converted to a free version, not erased immediately. If you change the scanner's free-version reclamation logic, you can either keep them around forever (storage bloat) or delete them too eagerly (data loss). Run make test-versioning and make test-decom after changes.

Decommission is one-way

Once a pool decommission is started, the pool's data is being moved out. Pausing is supported but cancelling mid-decom is not — by the time you'd cancel, some objects already have their canonical copy on the target pool.

Never run two MinIO processes against the same drives

format.json carries a deployment ID; two processes will conflict and may corrupt shards. The dev mode build tag (dev) loosens some checks; the production build is strict.

Site replication has many moving parts

cmd/site-replication.go is 189 KB. A change that touches only one resource type (e.g. service accounts) often needs to update three places: the source-side hook in the relevant subsystem, the wire type in madmin-go, and the receive side in cmd/admin-handlers-site-replication.go. Run all three make test-site-replication-* suites.

Veeam-specific code path

cmd/veeam-sos-api.go adds Veeam-specific HEAD/GET responses. Don't mistake the Veeam test failures for MinIO bugs unless you can reproduce against a non-Veeam workload.

Tier transitions interact with replication

A transitioned object's data lives on the warm backend; replication needs to re-fetch it before sending to a target. Combinations of replication + ILM + Object Lock have the most complex test coverage in the repo (make test-ilm, make test-ilm-transition).