workerd error: R2 binding not found in preview environment

Fix R2 binding not found in preview environment

TL;DR

R2 bucket bindings declared only at the top level of wrangler.toml may not resolve inside preview or named environments. Add the r2_buckets binding under the environment block the preview uses (for example [[env.preview.r2_buckets]]), confirm the bucket exists, and redeploy the preview.

Verbatim error

workerd error: R2 binding not found in preview environment

Steps

1. Open wrangler.toml and identify which environment the preview uses (env.preview for wrangler dev, or your named env). Expected: you know the exact env name.
2. Add the binding under that environment, e.g. [[env.preview.r2_buckets]] with the same binding name and bucket_name. Expected: the binding is present in the env block.
3. Confirm the bucket exists: npx wrangler r2 bucket list. Expected: your bucket_name appears in the list.
4. Redeploy (or restart dev) targeting that environment. Expected: boot logs show the binding attached.
5. Access env.MY_BUCKET in a preview request. Expected: no "binding not found" error.

Use this when

• R2 works in production but throws "binding not found" in preview or dev
• You recently added a named environment to wrangler.toml
• Pages preview deployments cannot see the bucket

Not for this skill when

• The bucket is missing in every environment (create the bucket first)
• The bucket_name is wrong (fix the name)
• The issue is an R2 custom domain or public access setting

Variant phrasings

• r2 binding undefined preview
• env bucket not found workers preview
• r2_buckets env override missing
• R2 binding missing wrangler dev

Why it happens

Preview runs resolve bindings from their environment block. A bucket bound only at the top level is not reliably visible inside named or preview environments, so env.MY_BUCKET resolves to nothing and the runtime reports the binding as not found.

Edge cases

• The bucket_name must exist in the same account you deploy to.
• Preview often points at the production bucket; use a separate bucket for destructive tests.
• wrangler dev without --env uses the top-level config, which is why the bug only shows in some setups.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_gdXoDyYFciLdxMg84mhqug