Introduction

Deleting a versioned S3 bucket is more involved than deleting a normal bucket because removing the visible files is not enough. S3 stores historical object versions and delete markers, and the bucket cannot be removed until those are gone as well. The AWS CLI gives you the right low-level commands, but you have to delete the contents in the right order.

Understand What Versioning Leaves Behind

In a non-versioned bucket, deleting an object removes it. In a versioned bucket, deleting an object usually creates a delete marker and leaves older versions intact. From the console the bucket may look empty, but from the API it still contains data.

For a full cleanup, you need to remove:

• current and noncurrent object versions
• delete markers
• any protected objects that are blocked by retention or policy

That is why aws s3 rb --force is not the right mental model for versioned buckets. You need s3api commands that include VersionId.

Verify You Are Deleting the Right Bucket

Before doing anything destructive, confirm the AWS identity and inspect the bucket state.

aws sts get-caller-identity
aws s3api get-bucket-versioning --bucket my-versioned-bucket
aws s3api list-object-versions --bucket my-versioned-bucket

That first command is worth making a habit. In multi-account environments, the real risk is not syntax. It is deleting the right thing in the wrong account.

Delete All Object Versions

The delete-objects API accepts a JSON payload with both key names and version IDs. A practical way to build that payload is to ask the CLI to reshape the output for you.

1aws s3api list-object-versions \
2  --bucket my-versioned-bucket \
3  --query '{Objects: Versions[].{Key: Key, VersionId: VersionId}}' \
4  --output json > versions.json
5
6aws s3api delete-objects \
7  --bucket my-versioned-bucket \
8  --delete file://versions.json

After that, run list-object-versions again. If the bucket is large, the response may have been paginated, so one pass is not always enough.

Delete the Delete Markers Too

This is the step many people miss. Delete markers are their own entries and also have version IDs.

1aws s3api list-object-versions \
2  --bucket my-versioned-bucket \
3  --query '{Objects: DeleteMarkers[].{Key: Key, VersionId: VersionId}}' \
4  --output json > markers.json
5
6aws s3api delete-objects \
7  --bucket my-versioned-bucket \
8  --delete file://markers.json

When both the Versions list and the DeleteMarkers list are empty, the bucket is finally empty in the way S3 requires.

Remove the Bucket Itself

Once versioned contents are gone, the final bucket deletion is straightforward.

aws s3api delete-bucket --bucket my-versioned-bucket

To verify that it really disappeared:

aws s3api head-bucket --bucket my-versioned-bucket

If that still succeeds, you missed some versioned contents or you are hitting a protection feature such as Object Lock.

Large Buckets Need Repetition and Verification

For small buckets, a couple of list-and-delete cycles are enough. For large buckets, pagination becomes the main operational concern. If you only delete the first page of results, delete-bucket will keep failing even though the visible part of the bucket looks empty.

A safe workflow is:

1. list versions
2. delete returned versions
3. list delete markers
4. delete returned markers
5. repeat until both lists are empty

If the bucket is very large, reviewed automation or S3 Batch Operations may be a safer operational choice than repeating long CLI commands by hand.

Watch for Compliance and Retention Features

Some buckets cannot be emptied immediately even with correct CLI usage. Object Lock, legal hold, lifecycle retention, or MFA delete can block removal. When that happens, the error is not about your delete syntax. It is the storage policy doing what it was configured to do.

In production systems, check those settings before scheduling a deletion window. You do not want to discover retention constraints halfway through a cleanup.

Common Pitfalls

The most common mistake is deleting only current objects. In a versioned bucket, old versions and delete markers still count as contents, so bucket deletion fails.

Another common problem is ignoring pagination. A single list-object-versions result is not proof that the whole bucket has been processed.

Teams also skip identity checks and region checks. Running the right command in the wrong AWS account is far more dangerous than a syntax error.

Summary

• A versioned S3 bucket must be emptied at the version level before it can be deleted.
• Remove both object versions and delete markers with s3api, not just current files.
• Verify the active account and bucket state before any destructive command.
• Re-run listing commands until the bucket has no versions and no delete markers left.
• Investigate Object Lock, retention, and MFA delete if cleanup still fails.