Solution skill
Workers: wire bindings so env names match your code
Complete solution
Shows how to fix workers: wire bindings so env names match your code. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.
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:
{
"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 2 · 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>