Introduction

Amazon S3 can redirect requests for one object to another location by storing redirect metadata on the object. This is most commonly used with S3 static website hosting, where an old key can point to a new key or even to an external URL.

How S3 Object Redirects Work

S3 object redirects are driven by the x-amz-website-redirect-location metadata field. Instead of serving the object's own content through the website endpoint, S3 returns a redirect response that points the client elsewhere.

Typical uses include:

• redirecting an old HTML path to a new one
• moving content without breaking bookmarked URLs
• forwarding a request to another object in the same bucket
• redirecting to an external site

The key thing to remember is that this is website-style redirect behavior, not a server-side object alias.

Redirecting to Another Object in the Bucket

Here is a simple AWS CLI example that creates an object whose website response redirects to a new path:

1aws s3api put-object \
2  --bucket my-site-bucket \
3  --key old-page.html \
4  --website-redirect-location /new-page.html

When a request hits the S3 website endpoint for old-page.html, S3 responds with a redirect to /new-page.html.

This is useful when reorganizing a static site without breaking incoming links.

Redirecting to an External URL

The redirect location can also be a full URL:

1aws s3api put-object \
2  --bucket my-site-bucket \
3  --key docs.html \
4  --website-redirect-location https://docs.example.com/start

That lets S3 act as a lightweight redirect source for web traffic that still arrives at the old object key.

Updating an Existing Object

If the object already exists and you want to replace its metadata with a redirect, use copy-object with metadata replacement:

1aws s3api copy-object \
2  --bucket my-site-bucket \
3  --copy-source my-site-bucket/old-page.html \
4  --key old-page.html \
5  --metadata-directive REPLACE \
6  --website-redirect-location /new-page.html

Metadata replacement matters because S3 object metadata is not edited in place the way a database row might be. In effect, you create a new object version with the desired metadata.

Static Website Hosting Context

The redirect behavior is most relevant when you are using the bucket as a static website. That is the context where path-style object redirects are typically used for web pages and legacy links.

If your application is using S3 purely as an object store behind signed REST requests, object redirect metadata may not fit the traffic pattern you want. In that case, CloudFront or application-level redirects may be the better design.

Redirect Object Versus Copying Content

A redirect object is not the same thing as copying or moving file contents. The redirected object is basically a pointer for HTTP clients.

Choose a redirect when:

• old URLs must remain valid
• the content has a canonical new location
• you want browser behavior to change location explicitly

Choose a copy or move when:

• clients should still receive content directly from the original key
• you are reorganizing internal storage rather than public URLs

Permissions Still Matter

The redirect only helps if the client can reach the object through the relevant endpoint. For public website behavior, the website endpoint and objects need appropriate access configuration. For controlled access patterns, the redirect design needs to fit your bucket policy and request flow.

So before debugging the redirect metadata itself, confirm:

• the object exists
• the website endpoint is the one being used
• bucket or object permissions are compatible with the access pattern

Common Pitfalls

The biggest pitfall is expecting S3 redirect metadata to behave like a magical internal object alias for every access style. It is fundamentally about HTTP redirect behavior, especially in website hosting scenarios.

Another pitfall is forgetting that updating object metadata often requires re-putting or copying the object with replacement metadata.

A third pitfall is confusing a relative redirect path such as /new-page.html with a full external URL. Both are valid, but they have different use cases.

Finally, do not ignore the broader delivery stack. If you use CloudFront in front of S3, test the redirect through the actual path your users hit, not just by looking at bucket settings.

Summary

• S3 object redirects are configured through x-amz-website-redirect-location
• They are most commonly used with S3 static website hosting
• Redirects can point to another object path or to a full external URL
• Updating an existing object often requires a copy or re-upload with replacement metadata
• Use redirects for URL continuity, not as a substitute for copying or relocating object content