sst.aws.StaticSite errorPage throwing a 502 without index set

[nicholasgubbins]

using the current set up to run a static site.

export const docs = new sst.aws.StaticSite("Docs", {
    domain: "docs." + domain,
    path: "./packages/docs",
    dev: false,
    build: {
        command: "bun run build",
        output: "./dist",
    },
    errorPage: "/404.html",
});

i'm running a vitepress site. sst v4.5.1

if i go to docs.domain/404.html i get the page and can verify it's there

however if i go to any actual 404 route, i get a 502 ERROR Failed to contact the origin.

This makes sense because the errorPage should be throwing only in the instance of a 403 or 404 from the origin, but why is the cloudfront function throwing a 502 from a simple s3 file fetch?

[nicholasgubbins]

claude analysis:

Now I have a clear picture of the issue. Let me trace through the relevant code path.

When errorPage is set in SST, the metadata stored in KV is:
{ "errorResponseCode": 404, "s3": { ... } }

Note: custom404 is explicitly set to undefined (so it's omitted from JSON) when errorPage is
truthy (line 1051 in static-site.ts):
custom404: hasErrorPage ? undefined : errorPage,

This means in the function:

• metadata.custom404 → undefined
• metadata.errorResponseCode → 404

The condition if(metadata.custom404 && !metadata.errorResponseCode) is always false when
errorPage is set — the function never rewrites the URL to the error page. Instead it falls
through to the S3 fallback (line 2791), which routes the original (non-existent) URI to S3. S3
returns a 403, and the function is relying entirely on CloudFront's distribution-level
customErrorResponses to intercept that 403 and serve the error page.

The 502 cause: The customErrorResponses makes a NEW origin request for /404.html, which goes back
through this viewer request function. At that point metadata is re-read from KV. If that KV read
fails (transient error, or the key was temporarily absent during redeployment), metadata is
undefined, and this line in routeSite throws immediately:

const baselessUri = metadata.base ? ... : event.request.uri;
// ^^^^^^^^^^^^^ TypeError: Cannot read properties of undefined

This uncaught exception causes CloudFront to emit the 502 — and it's especially likely on the
error page subrequest because that's a second round-trip to the KV store in the same user
request.

Fix — guard against null/undefined metadata before calling routeSite:

if (!metadata) return event.request;
const response = await routeSite(kvNamespace, metadata);
return response || event.request;

This makes the function fail open (pass through to the default origin) rather than throwing. If
you want to explicitly serve an error instead, you could return a static 503 response there.

There's also a secondary issue: because customErrorResponses is configured for both errorCode:
403 and errorCode: 404, if S3 ever returns 404 (rather than 403) for the error page file itself,
CloudFront would try to serve the error page for the error page request too. Per AWS docs, that
second request is not subject to custom error responses, so you won't get an infinite loop — but
you can get a confusing 404-for-404. Using errorCode: 403 only (which is what S3 returns for
missing objects when OAC is in use) is safer.

[ekaya97]

@nicholasgubbins

check out this issue
#6321 (comment)

claude's analysis is correct but it's making the wrong assumption about the kv store - try this: go into the CF distributions live KV store and remove the entry for xxxx:/404.html - it will work afterwards.

the issue is that the KVS is created WITH the 404.html entry, even though CF's request function expects it WITHOUT that entry. since the KV store always takes precedence, the 404 page should not be included - instead we link our custom page to the CF native error page to trigger for 404 and 403 to return the proper HTTP response (instead of 200) - i have no idea what exactly the PR linked to the issue above is missing, but I bet it's some form of exclusion for the errorPage in KV store creation/update.

@vimtor