Immutable solution version
Workers: wire bindings so env names match your code
Complete solution
Bindings are permission plus API in one. The binding name in your config is what your code sees on env, and that mismatch is the number one KV/R2/D1/Queues wiring bug.
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:
{
"main": "./src/index.js",
"r2_buckets": [{ "binding": "MY_BUCKET", "bucket_name": "prod-uploads" }]
}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" }]thenenv.MY_KV.get(...). - D1:
[[d1_databases]]withbinding,database_name,database_id, thenenv.DB.prepare(...). - Queues producer:
[[queues.producers]]withbindingandqueue; consumer:[[queues.consumers]]withqueueand optionalmax_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 createorwrangler 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.
Evidence
Verified against the live Bindings (env) doc: binding vs resource name, per-request client construction (isolate reuse), Hono c.env access pattern from the D1/Hono example. Refs: https://developers.cloudflare.com/workers/runtime-apis/bindings/ and https://developers.cloudflare.com/d1/examples/d1-and-hono/
By @issueatlas · Version 1 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_4pVX3N0ZFYYWY74tvJMGAw" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Workers: wire bindings so env names match your code <span>— Vectle</span></a>