🚨 AWS Error: 'The bucket you are attempting to access must be addressed using the specified endpoint' — Cause, Fix, and Troubleshooting Guide

Overview

S3 buckets are homed in a single region, and every request must reach the regional endpoint that owns the bucket. When a client talks to the wrong regional (or global) endpoint, S3 answers with an HTTP 301 PermanentRedirect telling you which endpoint to use instead. Unlike a browser redirect, most SDKs and the CLI do not silently follow it — the call fails.

You will see it surface from the CLI or an SDK:

An error occurred (PermanentRedirect) when calling the PutObject operation: The bucket you are attempting to access must be addressed using the specified endpoint. Please send all future requests to this endpoint.

It occurs whenever the region your client is configured for does not match the region the bucket actually lives in — a mismatched --region, a stale AWS_REGION, a copied config from another environment, or an SDK defaulting to us-east-1 while the bucket is elsewhere.

Symptoms

• PutObject, GetObject, HeadBucket, or ListObjectsV2 fails with PermanentRedirect (HTTP 301).
• The same command works against a different bucket in your “home” region but fails for one created elsewhere.
• aws s3 ls (which auto-resolves region) works, but aws s3api ... calls fail.
• Terraform or an SDK app fails only against buckets in a non-default region.

aws s3api put-object --bucket app-artifacts-REDACTED --key test.txt --region us-east-1

An error occurred (PermanentRedirect) when calling the PutObject operation: The bucket you are attempting to access must be addressed using the specified endpoint.

Common Root Causes

1. The client region does not match the bucket region

The most common cause. Your --region / AWS_REGION says us-east-1 but the bucket was created in eu-west-1.

2. A stale or copied AWS_REGION / profile

An environment variable or profile copied from another account or CI job pins the wrong region for every call.

3. SDK defaulting to us-east-1

Some SDKs and older tooling default to us-east-1 (the global endpoint) when no region is set, which only works for buckets that happen to live there.

4. Virtual-hosted vs. path-style against the wrong endpoint

Hardcoding s3.amazonaws.com (the global/us-east-1 endpoint) in a tool or presigned URL routes every request to one region regardless of where the bucket lives.

5. A very recently created bucket

Immediately after creation, the global endpoint may still redirect while the bucket’s region propagates. Addressing the regional endpoint directly avoids the redirect.

How to diagnose

Step 1: Ask S3 where the bucket actually lives

aws s3api get-bucket-location --bucket app-artifacts-REDACTED

{ "LocationConstraint": "eu-west-1" }

A null/empty LocationConstraint means us-east-1; any other value is the region you must target.

Step 2: Check what region your client is using

aws configure get region
echo "AWS_REGION=$AWS_REGION AWS_DEFAULT_REGION=$AWS_DEFAULT_REGION"

If this disagrees with Step 1, that is your bug.

Step 3: Confirm the fix resolves the redirect

aws s3api head-bucket --bucket app-artifacts-REDACTED --region eu-west-1 && echo "OK in eu-west-1"

Fixes

Point the call at the bucket’s real region

aws s3api put-object --bucket app-artifacts-REDACTED --key test.txt \
  --body ./test.txt --region eu-west-1

Set the region durably for the profile or environment

aws configure set region eu-west-1 --profile prod
# or, per shell / CI:
export AWS_REGION=eu-west-1

Configure the region in SDK code, not the endpoint

Set the region in the client constructor (region_name="eu-west-1" in boto3, Region in the Go/JS SDKs) and let the SDK build the correct endpoint. Do not hardcode s3.amazonaws.com.

For multi-region tooling, resolve the region per bucket

Call get-bucket-location first and pass the result as --region, so a tool that touches many buckets always addresses the correct endpoint.

What to watch out for

• LocationConstraint: null means us-east-1 — don’t treat the empty value as “unknown.”
• Presigned URLs are region-specific; generate them with the bucket’s region or they redirect for the recipient.
• aws s3 ls/cp auto-resolve the bucket region, which can mask a misconfigured AWS_REGION that then breaks s3api calls and SDK code.
• Setting the wrong region also causes SDKs to sign with the wrong region, producing SignatureDoesNotMatch instead of PermanentRedirect in some code paths.

Related

• AWS Error: ‘NoSuchBucket’ — the bucket name resolves to nothing at all (vs. wrong region).
• AWS Error: ‘SignatureDoesNotMatch’ — a wrong region can also break request signing.
• AWS Error: ‘403 Forbidden’ on HeadObject — permission problems on an otherwise correctly-addressed bucket.