CloudFront Behavior Requirements

A browsable S3 prefix only works when CloudFront sends that path through the directory-browser Lambda@Edge function. Updating Lambda code by itself is not enough.

Hard requirement: publish and attach a numbered Lambda@Edge version

Lambda@Edge does not run $LATEST. After changing lambda-edge-directory-browser/index.mjs, you must:

  1. Deploy the Lambda code.
  2. Publish a new numbered Lambda version.
  3. Copy the numbered version ARN.
  4. Attach that numbered version ARN to the appropriate CloudFront behavior.
  5. Wait for CloudFront to finish deploying.

If CloudFront is still associated with an older numbered version, the site will keep running the old code even though Lambda shows newer code in the editor.

Hard requirement: every browsable prefix needs a matching behavior

Each public browse root should be handled by a CloudFront behavior that reaches the correct S3 origin and has the directory-browser Lambda attached at Origin response.

Public URLBucketPrefixBehavior pattern
https://8k.art/beta/www.8k.artbeta//beta/*
https://8k.art/_docs/www.8k.art_docs//_docs/*
https://8k.press/beta/www.8k.pressbeta//beta/*
https://8k.press/images/www.8k.pressimages//images/*
https://define.com/beta/www.define.combeta//beta/*

Symptom: “ReferenceError: fetchFreshS3Listing is not defined”

This means CloudFront is running a viewer version that contains the broken v75 code path. Deploy v76 or newer, publish a numbered Lambda@Edge version, and attach that version to the CloudFront behavior.

Symptom: browser shows a redirect HTML/XML page instead of a directory listing

If a page such as https://define.com/beta/ shows a redirect document like https://define.com/8k.art/beta/, CloudFront is serving an ordinary S3 object instead of the directory-browser Lambda output.

Check these items:

  1. The CloudFront distribution for the domain has a behavior matching the prefix, such as /beta/*.
  2. That behavior points to the correct S3 origin, such as www.define.com.
  3. That behavior has the current numbered directory-browser Lambda version attached at Origin response.
  4. The old redirect object, often beta/index.html, is removed or no longer being served before the Lambda response path.
  5. CloudFront deployment has completed.
  6. Any stale path has been invalidated.

Verification checklist

After deployment, open each directory and use View Source. A healthy generated listing has a source marker near the top:

<!-- directory-browser-viewer-version: v78 -->
<!-- directory-browser-updater-baseline: v67 -->
<!-- directory-source: prebuilt-json-index -->

or, while JSON is not yet active:

<!-- directory-browser-viewer-version: v78 -->
<!-- directory-browser-updater-baseline: v67 -->
<!-- directory-source: live-s3-listing -->

If neither marker appears, the directory-browser Lambda is probably not running for that URL.

Safe operating setting for the updater

For bulk uploads, keep the updater Lambda reserved concurrency at:

s3-directory-index-updater
Reserved concurrency: 1

This prevents many updater Lambdas from running in parallel while S3 Browser is uploading a build.