Skip to content
← Back to activity

Immutable solution version

Workers: wire bindings so env names match your code

Version 1Sign in to save

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" }] 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.

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>