create_bucket examples don't explain Region requirements

[jrotenstein]

Describe the issue

The two examples shown at the bottom of the create_bucket() page do not provide sufficient context. Specifically, the second example only works when used with the us-east-1 region. If used with any other region, it returns an IllegalLocationConstraintException error.

See StackOverflow discussion: python - Unexpected response output when creating an S3 bucket using boto3 - Stack Overflow

Links

https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3/client/create_bucket.html

[RyanFitzSimmonsAK]

Hi @jrotenstein, thanks for reaching out. The first example (LocationConstraint included) is for the case that you are using a region other than us-east-1. I think the intention of the second example is demonstrate the behavior described in the LocationConstraint documentation. Specifically,

If you don’t specify a Region, the bucket is created in the US East (N. Virginia) Region (us-east-1) by default.

To clarify, you'd like both examples to explain that nuance?

[jrotenstein]

Hi @RyanFitzSimmonsAK.

If you don’t specify a Region, the bucket is created in the US East (N. Virginia) Region (us-east-1) by default.

This isn't fully accurate. If the client is created in a different region other than us-east-1 (eg Sydney), then attempting to create a bucket without specifying a LocationConstraint results in:

botocore.exceptions.ClientError: An error occurred (IllegalLocationConstraintException) when calling the CreateBucket operation: The unspecified location constraint is incompatible for the region specific endpoint this request was sent to.

Therefore, the second example in the documentation is only valid if the client is using us-east-1. It should somehow mention this, otherwise a lot of customers will be confused as to why the sample code isn't working.

In fact, even the first example only works if the client region is us-east-1, or the region used in the client matches the region specified in the LocationConstraint.

I appreciate that this is probably too much detail to put in the documentation, but as per the linked StackOverflow question, it is confusing some users (and me!).

It would probably be better for examples to focus on something that works for ALL regions rather than showing exceptions that only work in us-east-1. Or at least mention that the client region should typically match the LocationConstraint.

Anyway, just passing-on the information. It's up to you folks to determine what you'd like to include. :)

[github-actions]

This issue is now closed. Comments on closed issues are hard for our team to see.
If you need more assistance, please open a new issue that references this one.