Why might context.env.MESSAGES still be undefined in a Cloudflare Pages Function after a KV binding named MESSAGES was added in the dashboard?
answer
- bindings attach at deploy time
- preview and production configured apart
- a Wrangler file overrules the dashboard
- local dev reads its own config
basics
~20 sPages attaches bindings when a deployment is created, so the project needs a redeploy after a dashboard change. Preview and production keep separate bindings, a Wrangler file with pages_build_output_dir replaces dashboard settings, and wrangler pages dev reads only the Wrangler file or flags.
solid answer
~40 sPages Functions read bindings from `context.env`, and a Pages project resolves them per deployment and per environment. A binding added in the dashboard takes effect only on the **next deployment**, so an existing deployment keeps its old `env`. Bindings are set separately for **production** and **preview**, so a binding added only to production is missing on every preview URL. If the repository has a Wrangler file with `pages_build_output_dir`, that file is the **source of truth**: its settings apply on deploy and the dashboard shows those fields read-only. Locally, `wrangler pages dev` sees only what the Wrangler file or flags such as `--kv=MESSAGES` declare. Last, the binding name is case-sensitive and must match `MESSAGES` exactly. Secrets work the same way: set them with `wrangler pages secret put` before the deployment that reads them.
code
json · 11 lines{
"name": "contact-site",
"pages_build_output_dir": "./public",
"compatibility_date": "2026-10-01",
"kv_namespaces": [{ "binding": "MESSAGES", "id": "<PRODUCTION_NAMESPACE_ID>" }],
"env": {
"preview": {
"kv_namespaces": [{ "binding": "MESSAGES", "id": "<PREVIEW_NAMESPACE_ID>" }]
}
}
}go deeper
Recall that bindings appear on context.env by name and that a Pages project needs a new deployment after a binding is added.
Explain the production and preview split, the Wrangler file as source of truth with pages_build_output_dir, and how wrangler pages dev builds its own env.
Work the diagnosis in order: which deployment and environment served the request, where its configuration came from, and whether a redeploy happened, then fix local parity.
Choose one source of truth for the team: a reviewed Wrangler file keeps bindings in version control, at the cost of losing dashboard edits for those fields.
## Where `context.env` comes from A **binding** connects a Pages Function to a Cloudflare resource, such as a KV namespace, a D1 database or an R2 bucket, or to a value such as an environment variable or secret. In a route handler, every binding appears on **`context.env`** under its binding name, so a KV namespace bound as `MESSAGES` is `context.env.MESSAGES`, with methods such as `get()` and `put()`. Three facts about Pages bindings explain nearly every "undefined binding" report: - they are fixed **when a deployment is created**; - they are configured **per environment**, production and preview; - they come from **one source**: the dashboard or a Wrangler file, not both. ## Cause 1: no deployment since the change The dashboard steps for adding a binding end with "redeploy your project for the binding to take effect". A deployment carries the configuration it was created with, so the live deployment keeps its old `env` until a new one is built, by a push to the connected branch or a new `wrangler pages deploy`. Secrets follow the same rule: a secret must exist before the deployment that reads it is created. ## Cause 2: the wrong environment A Pages project has two configuration sets: | Environment | Used by | |---|---| | production | deployments from the production branch | | preview | every other branch deployment and its preview URL | A binding added only under production is absent on preview URLs, which is exactly where a new contact form is usually tested. Pages has no per-branch configuration: one preview set covers every preview deployment. ## Cause 3: a Wrangler file is the source of truth A Pages project can keep its configuration in `wrangler.jsonc` (or `wrangler.toml`) once the file has a **`pages_build_output_dir`** key. From then on: 1. The file's settings apply on each deployment, and the dashboard shows those fields **read-only**. 2. A binding the file does not declare is not attached, whatever the dashboard showed earlier. 3. Overrides use `env.preview` and `env.production`, the only two environment names Pages accepts; Wrangler refuses any other name when it validates the file for a deploy. 4. Bindings such as `kv_namespaces` and `vars` are **non-inheritable**: once `env.production` overrides one of them, it must declare every non-inheritable key the file uses, or the deploy fails validation even though local runs work. `wrangler pages download config <project>` writes the dashboard's current settings into a Wrangler file, which is the safe way to switch. ## Cause 4: local development `wrangler pages dev` never reads dashboard settings. It builds `env` from: - the Wrangler file in the project, with local simulations of KV, D1 and R2; - flags such as `--kv=MESSAGES`, `--d1=DB`, `--r2=BUCKET` and `--binding=NAME=value`, which take precedence over the file; - secrets from a `.dev.vars` file next to the Wrangler file, kept out of Git. A binding that exists in production but not in either local source is `undefined` locally. ## Cause 5: a name mismatch or an unsupported binding - Binding names are case-sensitive: `messages` and `MESSAGES` are different bindings. - Pages Functions support a subset of Workers bindings. A queue can only be bound as a producer, so consuming it takes a separate Worker, and a Durable Object class must be defined in a separate Worker and bound to the project. ## A diagnosis order 1. Open the deployment that served the failing request and check its environment and creation time. 2. Check the binding under that environment, or in the Wrangler file if one exists. 3. Redeploy. 4. For local runs, read the table `wrangler pages dev` prints at startup under "Your Worker has access to the following bindings"; a binding missing there is missing from the Wrangler file, the flags or `.dev.vars`. A small guard in the handler turns the silent failure into a clear one: if `context.env.MESSAGES` is missing, log it and answer `500` with a generic message rather than throwing a `TypeError` on `put()`. ## Keeping the token a secret The contact API's `API_TOKEN` is a **secret**, not a var: set it with `wrangler pages secret put API_TOKEN --project-name contact-site`, or as an encrypted variable in the dashboard. A var in the Wrangler file is stored in plain text in the repository. For local runs, put `API_TOKEN="..."` in `.dev.vars`; the startup table of `wrangler pages dev` lists it with its value shown as `(hidden)`.
- A Pages project's Wrangler file overrides vars under env.production but not kv_namespaces. What happens on deploy?The deploy fails validation. In a Pages Wrangler file, `vars` and the binding lists are non-inheritable keys, and overriding any one of them for an environment requires declaring all of them there. Local `wrangler pages dev` still works, which is why the mistake often surfaces only at deploy.
- Why should API_TOKEN not live under vars in a Pages project's Wrangler file?Vars are plain-text configuration committed with the repository and visible in the dashboard. A token belongs in a secret, set with `wrangler pages secret put` or as an encrypted variable in the dashboard, and in a Git-ignored `.dev.vars` file for local runs.
- A binding added in the dashboard reaches running deployments immediately.
- Bindings set for production also apply to every preview deployment.
- With pages_build_output_dir in the Wrangler file, dashboard binding edits still apply.
- wrangler pages dev reads bindings from the project's dashboard settings.
- Pages supports custom Wrangler environments such as env.staging.