s3: per-bucket limit of 1,000 objects prevents testing code that relies on S3's 1,000-item page and batch sizes

Open Beginner friendly
  • Is something wrong?
#30 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
72/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
aws, docker, java, rust
Domain
backend, databases

Research direction

Start with MAX_OBJECTS_PER_BUCKET in services/service-com-amazonaws-s3-amazons3/src/state.rs, then check how PutObject, CopyObject, and CompleteMultipartUpload enforce it. The report asks for more than 1,000 stored objects per bucket so S3 pagination and batch behavior can be tested; verify the limit no longer rejects writes above 1,000 and that listing can return a second page.

Written by the indexing model from the issue text.

Description

Before you file
  • I searched open and recently closed issues and found no report of this.
  • I checked that this still happens with the latest version of the emulator.
What happened

PutObject is refused once a bucket holds 1,000 objects. The first 1,000 objects are stored and the next write fails. With the AWS CLI the error is:

An error occurred (ValidationException) when calling the PutObject operation:
the bucket "repro-bucket" already holds the maximum of 1000 objects this emulator
keeps per bucket; delete an object before writing "prefix/query1000"

With the AWS SDK for Java 2.x the same refusal arrives as S3Exception ... Status Code: 400.

Which request is refused depends on arrival order, because the reproduction sends requests in parallel; here it was query1000. Exactly one request fails, and the bucket ends with 1,000 objects.

The limit is the constant MAX_OBJECTS_PER_BUCKET in services/service-com-amazonaws-s3-amazons3/src/state.rs, documented there as "NOT a fidelity claim". It counts stored versions, including noncurrent versions and delete markers, and also applies to CopyObject and CompleteMultipartUpload. I found no startup option, config.toml setting or environment variable to change it.

What you expected

All writes succeed. Amazon S3 has no limit on the number of objects in a bucket ("There is no max bucket size or limit to the number of objects that you can store in a bucket"): https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html

There are two different "1,000" values here, and only one of them is AWS behavior. The page size of ListObjectsV2 is 1,000: it returns "up to 1,000" objects "with each request", and by default "the response might contain fewer keys but will never contain more" (https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html). The limit of 1,000 objects per bucket is specific to this emulator.

With more than 1,000 objects, ListObjectsV2 returns 1,000 keys with IsTruncated=true and a NextContinuationToken, and a second request returns the remaining keys. I have not run this against AWS. The expectation comes from the documentation above.

Steps to reproduce

Environment: AWS Emulator 1.0.322 (LTS aarch64 RPM installed on an Amazon Linux 2023 image) in Docker on macOS, started with -b 0.0.0.0 -p 9297 --auth off and published with -p 127.0.0.1:9297:9297; the CA certificate was copied out of the container with docker cp to $HOME/.aws/emulator/9297/ca.pem. AWS CLI 2.35.19; Region us-east-1. Nothing else uses the emulator.

export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_CA_BUNDLE=$HOME/.aws/emulator/9297/ca.pem
export AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test
export AWS_REGION=us-east-1 AWS_DISABLE_HOST_PREFIX_INJECTION=true

aws s3api create-bucket --bucket repro-bucket
seq -w 1 1001 | xargs -P 8 -I{} \
  aws s3api put-object --bucket repro-bucket --key "prefix/query{}"
aws s3api list-objects-v2 --bucket repro-bucket --query 'length(Contents[])'

Result: exactly one put-object call fails with the error above, and the last command prints 1000. I ran this twice on a freshly started emulator and it reproduced both times.

The same happens with the AWS SDK for Java 2.x (path-style client) when a test writes 1,001 objects one after another.

Emulator version
Version: 1.0.322
Release date: 2026.11.10
Commit: 7753983c6e495ec3612695b1336bf4936fc7b7fd
Impact and workaround

Several S3 operations work in units of 1,000: ListObjectsV2 returns at most 1,000 keys per page by default, and DeleteObjects accepts up to 1,000 keys per request (https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html). With at most 1,000 objects in a bucket, code that uses the default page size or splits work into batches of 1,000 never reaches its second page or batch. Examples are a listObjectsV2Paginator call without maxKeys, and aws s3 rm --recursive or aws s3 sync over more than 1,000 keys.

Setting a small MaxKeys does produce a second page in the emulator, but only when the code under test lets the test change the page size. Ours does not, so our workaround is to skip that test against the emulator and cover it against a real bucket.

The comment on MAX_OBJECTS_PER_BUCKET says the limit is "set generously so no realistic workflow meets it". At 1,000, the first workflow that needs a second page or a second DeleteObjects batch meets it. The user guide's Limitations section also says "How much it can hold depends on your machine", which doesn't mention a fixed per-bucket limit.

Any value above 1,000 would let a second page exist (for example 2,000 to 10,000), while MAX_OBJECTS_TOTAL and the 64 MiB per-bucket byte budget would still bound memory. Making the limits configurable, or documenting them under Limitations, would also help.

Additional context

issues/things-that-now-work/20261027T235025Z-s3-6-net-new-root-causes-per-bucket.md (cause 2) reported the earlier 16 MiB per-bucket byte cap on UploadPart, which also surfaced as a ValidationException. That cap is now 64 MiB (MAX_OBJECT_BYTES_PER_BUCKET) rather than removed.

I understand from the comment in src/ops/put_object.rs that ValidationException is chosen on purpose because no S3 error code fits. I mention it only because clients see it as an unexpected error code.

Dominant language
Rust
Stars
2.2k
Forks
44
No merged PRs in 30d

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from aws/aws-emulator

All issues in aws/aws-emulator

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.