## TL;DR

Cloudflare's docs put it plainly: with bindings you never add secret keys to your Worker, the permission is embedded in the API itself. Deploying a bindings-only change may reuse existing isolates without reloading your code. Never cache clients derived from env (secrets, bucket handles) in global scope; construct per request so binding changes take effect.

## When to use

You are seeing this: A binding grants your Worker a capability, like reading an R2 bucket, and exposes it on the env object. Use this skill when you run into "Workers: wire bindings so env names match your code".

## When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

## Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

## Bindings: config names and code names must match

A binding grants your Worker a capability, like reading an R2 bucket, and exposes it on the `env` object. Cloudflare's docs put it plainly: with bindings you never add secret keys to your Worker, the permission is embedded in the API itself.

## The rule that breaks everyone

The `binding` string in your Wrangler config is the property name your code uses. The resource name is separate. Confusing them is the classic failure:

```jsonc
{
  "main": "./src/index.js",
  "r2_buckets": [{ "binding": "MY_BUCKET", "bucket_name": "prod-uploads" }]
}
```

```js
export default {
  async fetch(request, env) {
    await env.MY_BUCKET.put("key", request.body);
  }
};
```

Your code reads `env.MY_BUCKET` (the binding), not the bucket name `prod-uploads`. This applies to KV (`binding` vs namespace `id`), D1 (`binding` vs `database_id`), and Queues (`binding` vs `queue` name).

## Per-resource shapes

- KV: `kv_namespaces = [{ binding = "MY_KV", id = "abc123" }]` then `env.MY_KV.get(...)`.
- D1: `[[d1_databases]]` with `binding`, `database_name`, `database_id`, then `env.DB.prepare(...)`.
- Queues producer: `[[queues.producers]]` with `binding` and `queue`; consumer: `[[queues.consumers]]` with `queue` and optional `max_batch_size`.
- Python Workers: same config, access via `self.env.MY_BUCKET`.

## The stale-global trap

Deploying a bindings-only change may reuse existing isolates without reloading your code. Never cache clients derived from `env` (secrets, bucket handles) in global scope; construct per request so binding changes take effect. The docs show exactly this with a `new Client(env.MY_SECRET)` per-request pattern.

## Checklist

- After `wrangler kv:namespace create` or `wrangler d1 create`, copy the printed config block into your Wrangler file verbatim, do not retype ids.
- In Hono, bindings arrive on `c.env`, same names: type them (`type Bindings = { DB: D1Database }`) so mismatches fail at build.
- In local dev, bindings without a local id fall back to remote or fail; pass the id explicitly or accept the remote call.
