Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

A React Router route returns 403 or 404 from S3 when you refresh

Error403 Forbidden when refreshing /dashboard on the S3 website URL

Short answer

Client routes like /dashboard are not files in the bucket, so S3 answers 404 or 403 when the URL is opened directly. Configure the host to serve index.html for them: an error document on the S3 website endpoint, or custom error responses in CloudFront that map 403 and 404 to /index.html with status 200.

  • Applies to React Router 7, Vite 7, Amazon S3 static website hosting, Amazon CloudFront
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Request a deep link and read the status line. 404 and 403 point at different causes below.

    curl -sI http://my-bucket.s3-website.eu-west-1.amazonaws.com/dashboard | head -n 1
  2. 2Match what you see, then jump to its fix

    1. 1404 Not Found for a path that is not a file in the bucketNo error document points at index.htmlFix
    2. 2403 Forbidden instead of 404, on the website endpointObjects are not publicly readable, so S3 answers 403Fix
    3. 3The site is behind CloudFront and deep links return 403 or 404 while / worksCloudFront passes the origin's 403 or 404 on to the browserFix

What does the error look like?

  • 403 Forbidden when refreshing /dashboard on the S3 website URL
  • 404 Not Found when opening a deep link such as /users/42 directly
  • The home page loads, but only in-app navigation works

Cause 1 of 3

No error document points at index.html

1Check

The S3 website endpoint answers 404 when the URL refers to an object key that does not exist. A custom error document, set in the static website hosting settings, is returned for 4XX errors.

curl -sI http://my-bucket.s3-website.eu-west-1.amazonaws.com/dashboard | head -n 1

2Fix

Set the error document to index.html next to the index document, then upload both.

aws s3api put-bucket-website --bucket my-bucket \
  --website-configuration file://website.json

# website.json
{
  "IndexDocument": { "Suffix": "index.html" },
  "ErrorDocument": { "Key": "index.html" }
}

3Verify

Open the deep link in the browser; the app should load and React Router should render the route.

curl -s http://my-bucket.s3-website.eu-west-1.amazonaws.com/dashboard | head -c 200

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 2 of 3

Objects are not publicly readable, so S3 answers 403

1Check

The website endpoint answers 403 when the request translates to an object that is not publicly readable. The object owner must make objects readable through a bucket policy or an ACL.

curl -sI http://my-bucket.s3-website.eu-west-1.amazonaws.com/index.html | head -n 1

2Fix

Allow public reads for the website objects with a bucket policy or ACL, as the S3 page requires for the website endpoint.

# S3 console: bucket > Permissions > Bucket policy, allow s3:GetObject for the website objects, or serve the private bucket through CloudFront

3Verify

Request an existing file such as /index.html and expect 200.

curl -I http://my-bucket.s3-website.eu-west-1.amazonaws.com/index.html

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 3 of 3

CloudFront passes the origin's 403 or 404 on to the browser

1Check

CloudFront returns the status code it receives from the origin unless you add a custom error response. Some proxies and firewalls intercept 4xx and 5xx responses, and a 200 is not intercepted.

curl -sI https://d111111abcdef8.cloudfront.net/dashboard | head -n 1

2Fix

In the distribution, create custom error responses for 403 and 404 with response page path /index.html and response code 200 (200 is one of the allowed values).

# CloudFront console: Distribution > Error pages > Create custom error response
# HTTP error code: 403, Response page path: /index.html, HTTP response code: 200
# Repeat for 404.

3Verify

Wait for the distribution to deploy, then request a deep link and expect 200 with your index.html.

curl -sI https://d111111abcdef8.cloudfront.net/dashboard | head -n 1

Confirmed by docs.aws.amazon.com

Did this fix it?

How do I stop it coming back?

  • Treat the host as a rewrite problem from day one: any path that is not a file must return index.html.
  • Serve it with status 200 where you can, so crawlers and proxies do not treat your routes as errors.
  • Keep the S3 error document name exactly equal to the uploaded file; the name is case sensitive.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.