Add an S3 website error document

Part 58 of AWS from Zero. This lesson keeps the scope to one S3 behavior you can verify from the terminal.

What we are learning

An error document gives website visitors a controlled response body when S3 cannot serve the requested key.

Before you run it

aws sts get-caller-identity
REGION="ap-south-1"
BUCKET="replace-with-your-private-demo-bucket"

Use a private general purpose bucket that you own. Replace every placeholder before running a write or delete command.

The command

cat > website.json <<'EOF'
{
  "IndexDocument": {"Suffix": "index.html"},
  "ErrorDocument": {"Key": "error.html"}
}
EOF
 
aws s3api put-bucket-website \
  --bucket "$BUCKET" \
  --website-configuration file://website.json

A successful configuration command may return no output. Treat inspection as a separate required step.

Inspect the result

aws s3api get-bucket-website \
  --bucket "$BUCKET" \
  --query "{Index:IndexDocument.Suffix,Error:ErrorDocument.Key}" \
  --output table

Read the returned fields rather than assuming the write succeeded exactly as intended.

One tiny variation

echo '<h1>Not found</h1>' > error.html
aws s3 cp error.html "s3://$BUCKET/error.html" \
  --content-type text/html

The configured error key must exist and be readable through the website access model.

Common mistake

A custom error document does not change every HTTP status into 404; S3 website endpoint behavior depends on the failure.

Cleanup

aws s3api delete-bucket-website --bucket "$BUCKET"
aws s3 rm "s3://$BUCKET/error.html"
rm website.json error.html

Delete the website subresource and temporary object.

Next, we will learn Create an S3 website redirect object.

Official AWS CLI reference