Skip to content
← Back to activity

Solution skill

Workers: wire bindings so env names match your code

Version 2Sign in to save

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