Cloudflare Wrangler — binding not found in Worker

A Cloudflare Worker throws "binding X does not exist" because the KV, R2, or D1 binding in code is not declared in wrangler.toml or the dashboard.

intermediatedebuggingcloudflareworkers

Symptoms

error: binding "MY_KV" does not exist
The Worker works locally with wrangler dev but fails in production
TypeError: Cannot read properties of undefined (reading "get")

Possible causes

The binding name in code does not match the binding name in wrangler.toml
The binding is declared in wrangler.toml but not deployed to the environment
The binding was removed from the dashboard but code still references it

Diagnosis steps

Check wrangler.toml bindings

cat wrangler.toml | grep -A5 kv_namespaces

Interpretation

Confirm the binding ID and name match what the code expects.

List deployed bindings

npx wrangler deploy --dry-run

Interpretation

The dry run shows which bindings are attached to the deployed Worker.

Root cause

The binding is not declared in the environment configuration, so the Workers runtime does not inject it into the global scope, causing the reference to be undefined.

Fix

Add the binding to wrangler.toml with the correct name and ID, deploy with wrangler deploy, and ensure the binding name in code matches the configuration exactly.

Verify the fix

Deploy the Worker and test the endpoint that uses the binding; confirm the KV or R2 operation succeeds.

Symptom walkthrough

A Cloudflare Worker throws “binding X does not exist” because the KV, R2, or D1 binding in code is not declared in wrangler.toml or the dashboard. The error appears in production but may not surface in local development because the conditions that trigger it depend on the deployment environment or runtime configuration. Understanding the full symptom set helps distinguish this issue from similar errors.

Diagnosis in practice

Follow the diagnosis steps in the frontmatter to isolate the cause. Each step includes a command and an interpretation of the output. The goal is to narrow down whether the issue is in the configuration, the runtime, or the application code. Reproduce the error in a minimal setup before applying a fix.

Root cause

The binding is not declared in the environment configuration, so the Workers runtime does not inject it into the global scope, causing the reference to be undefined.

Fix

Add the binding to wrangler.toml with the correct name and ID, deploy with wrangler deploy, and ensure the binding name in code matches the configuration exactly. After applying the fix, monitor the system to confirm the error does not recur under load or in different environments.

Verification

Deploy the Worker and test the endpoint that uses the binding; confirm the KV or R2 operation succeeds. If the verification passes, the fix is confirmed; if not, re-examine the diagnosis steps for missed contributing factors.

Diagnostic commands

Run these commands to reproduce and diagnose the issue:

cat wrangler.toml | grep -A5 kv_namespaces
npx wrangler deploy --dry-run