# 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

```text
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