Skip to content

CloudFront Custom Error Pages Setup

This document explains how to configure CloudFront to show a custom 404 page instead of XML error responses.

Why This Matters

By default, CloudFront returns raw XML errors for 403/404 responses: 

<Error>
  <Code>AccessDenied</Code>
  <Message>Access Denied</Message>
</Error>

With custom error pages, users see a friendly 404 page instead.

Setup via AWS Console

Distribution: E1XTO7UTGAUI9L (docs.vell.ai)

  1. Go to CloudFront console
  2. Select distribution E1XTO7UTGAUI9L
  3. Go to Error Pages tab
  4. Click Create Custom Error Response

First Error Response (403 → 404): - HTTP Error Code: 403 Forbidden - Customize Error Response: Yes - Response Page Path: /404.html - HTTP Response Code: 404 Not Found - Error Caching Minimum TTL: 300 seconds (5 minutes)

Click Create

Second Error Response (404): - HTTP Error Code: 404 Not Found - Customize Error Response: Yes - Response Page Path: /404.html - HTTP Response Code: 404 Not Found - Error Caching Minimum TTL: 300 seconds

Click Create

Setup via AWS CLI

# Get current distribution config
aws cloudfront get-distribution-config \
  --id E1XTO7UTGAUI9L \
  --output json > /tmp/cf-config.json

# Extract ETag (needed for update)
ETAG=$(aws cloudfront get-distribution-config \
  --id E1XTO7UTGAUI9L \
  --query 'ETag' \
  --output text)

# Edit /tmp/cf-config.json and add to DistributionConfig:
# Under "CustomErrorResponses": {
#   "Quantity": 2,
#   "Items": [
#     {
#       "ErrorCode": 403,
#       "ResponsePagePath": "/404.html",
#       "ResponseCode": "404",
#       "ErrorCachingMinTTL": 300
#     },
#     {
#       "ErrorCode": 404,
#       "ResponsePagePath": "/404.html",
#       "ResponseCode": "404",
#       "ErrorCachingMinTTL": 300
#     }
#   ]
# }

# Update distribution
aws cloudfront update-distribution \
  --id E1XTO7UTGAUI9L \
  --distribution-config file:///tmp/cf-config.json \
  --if-match $ETAG

CloudFormation Template Addition

If using CloudFormation, add this to your distribution config:

CustomErrorResponses:
  - ErrorCode: 403
    ResponseCode: 404
    ResponsePagePath: /404.html
    ErrorCachingMinTTL: 300
  - ErrorCode: 404
    ResponseCode: 404
    ResponsePagePath: /404.html
    ErrorCachingMinTTL: 300

Verify It Works

After configuration:

  1. Wait 5-10 minutes for CloudFront to update
  2. Visit a non-existent page: https://docs.vell.ai/nonexistent/
  3. Should see MkDocs 404 page instead of XML error

The 404 Page

MkDocs Material automatically generates /404.html with: - Site navigation intact - Search functionality - Link back to home page - Professional styling matching your docs

This is already deployed in your vell-docs bucket at /404.html.

Benefits

✅ Better UX - Users see a helpful 404 page with navigation ✅ Consistent Design - 404 page matches your docs theme ✅ SEO Friendly - Returns proper 404 status code ✅ Security - Hides S3 bucket structure from error messages

Troubleshooting

Custom error page not showing: - Check that /404.html exists in S3 bucket - Verify error response configuration - Clear CloudFront cache: aws cloudfront create-invalidation --distribution-id E1XTO7UTGAUI9L --paths "/*" - Try in incognito mode to bypass browser cache

Still seeing XML errors: - Wait 5-10 minutes for CloudFront deployment - Check distribution status is "Deployed" - Verify S3 bucket policy allows CloudFront to read /404.html