skip to content

In Workers KV, how do you seed thousands of site-configuration keys at once when the Worker binding offers no bulk write?

level: middleimportance: should knowfreq 30%

answer

  1. the binding writes one key per call
  2. a JSON array file from the CLI
  3. the REST API's bulk endpoint
  4. Wrangler 4 starts in local mode

basics

~20 s

Write them outside the Worker: wrangler kv bulk put with a JSON array file, or the REST API's bulk endpoint, which takes up to 10,000 pairs per request. In Wrangler 4 the command writes to local storage unless it is given --remote.

solid answer

~40 s

The binding's `put()` writes one key per call, and the documentation states that bulk writes are not supported through it. Bulk loads go through `wrangler kv bulk put <filename> --binding FLAGS --remote` (or `--namespace-id`), where the file is a JSON array of objects with `key` and `value` and optional `expiration`, `expiration_ttl`, `metadata` and `base64`, or through the REST API's bulk endpoint, which accepts up to 10,000 pairs and under 100 MB per request and reports `unsuccessful_keys` to retry. Since Wrangler 4, `kv` commands default to local mode, so without `--remote` the command prints `Success!` against the local simulation and the deployed Worker sees nothing. Each pair is billed as one write, exactly as a `put()` would be.

code

json · 5 lines
json
[
  { "key": "site:eu:theme", "value": "dark" },
  { "key": "site:eu:banner", "value": "{\"on\":true}", "metadata": { "owner": "web" } },
  { "key": "cache:eu:promo", "value": "spring", "expiration_ttl": 3600 }
]

go deeper

for a junior

Recall that the Worker binding writes one key at a time and that bulk loads go through wrangler kv bulk put or the REST API.

for a middle

Explain the JSON file format, the 10,000-pair request limit, unsuccessful_keys, and why Wrangler 4 needs --remote to reach the real namespace.

for a senior

Catch a pipeline that reports success against local storage, make loaders write from one process with retries, and verify a sample remotely.

for a principal

Own where configuration originates and how it reaches KV, so bulk loads are repeatable, audited and never hand-run against production.

## Why the Worker is the wrong place for a bulk load The Workers KV binding exposes `get()`, `getWithMetadata()`, `put()`, `list()` and `delete()`. Reads have a bulk form, `get()` with an array of up to 100 keys, but **writes do not**: `put()` takes one key and one value, and the documentation states plainly that bulk writes are not supported through the binding. Looping over thousands of `put()` calls inside a request also runs into the per-invocation limit of 1,000 operations to external services. Seeding a configuration store, such as a few thousand site entries generated from a source of truth, is therefore done from outside the Worker. ## Option 1: wrangler kv bulk put The Wrangler command reads a JSON file and uploads it: ```bash npx wrangler kv bulk put site-config.json --binding FLAGS --remote ``` - The positional argument is the **file**: a JSON array of objects. - **`--binding FLAGS`** finds the namespace through the Wrangler file's `kv_namespaces` entry; **`--namespace-id`** names it directly instead. - **`--remote`** targets the namespace in the Cloudflare account; **`--local`** targets the local simulation; **`--preview`** targets the namespace given as `preview_id`. Each object in the file has these fields: | Field | Required | Meaning | |---|---|---| | `key` | yes | the key name | | `value` | yes | a string value | | `expiration` | no | absolute UNIX time in seconds | | `expiration_ttl` | no | seconds from now, at least 60 | | `metadata` | no | a JSON object up to 1024 bytes | | `base64` | no | `true` when `value` is base64-encoded binary | Wrangler sends the array to the bulk API in requests of 1,000 pairs and prints its progress for larger files. The companion commands are `wrangler kv bulk get` and `wrangler kv bulk delete`, which takes a file listing the keys to remove. ## The Wrangler 4 trap: local by default **Wrangler 4 made every command that can run locally or remotely default to local mode.** For KV this reversed the Wrangler 3 behaviour, where `kv` commands went to the API unless told `--local`. A CI job or script written before the upgrade, or copied from an old guide, keeps working without errors but writes somewhere else: ```plaintext Resource location: local Use --remote if you want to access the remote instance. Success! ``` The keys land in the local store under `.wrangler/state`, which local tools such as `wrangler dev` read. The production Worker reads the real namespace and finds nothing. The fix is to add `--remote` to every KV command in automation and to read the `Resource location` line in the job log. The old `kv:bulk put` spelling, renamed to `kv bulk put` in Wrangler 3.60.0, is also gone: the current Wrangler 4 release rejects it as an unknown command. ## Option 2: the REST API bulk endpoint A pipeline that already holds the data in another system can call the REST API directly, as the documentation's configuration-store example does from an external application: 1. Send up to **10,000 pairs** in one request, with the whole request **under 100 MB**. 2. Read the response's `successful_key_count` and **`unsuccessful_keys`**; the listed keys were not written to every storage backend and should be retried. 3. Respect the general Cloudflare API rate limits, which apply to every REST call and are lower for writes than the binding's. The REST route lives under `/accounts/{account_id}/storage/kv/namespaces/...`; the legacy `/workers/namespaces/` routes were deprecated in July 2026 with an end date of 15 October 2026. ## What a bulk write does not change - **Billing:** each pair counts as one write, the same as a `put()` call, whether it arrives through Wrangler, the API or the dashboard. - **Propagation:** bulk-written keys follow the same rules as any write, so locations that cached an old value or a not-found answer can serve it for 60 seconds or more. - **Per-key limits:** a key still takes at most one write per second, so a loader should not upload the same key twice in quick succession. - **Validation:** Wrangler checks the whole file before uploading and stops with an error listing items whose `key` or `value` is missing or not a string, so a malformed export fails before anything is written. A sensible seeding job writes from **one process**, which also follows the documented advice to avoid competing writes to the same key, and verifies a sample with `wrangler kv key get <key> --binding FLAGS --remote`.

  • In Workers KV, a nightly job must replace a few thousand configuration keys; why not run it as a Worker looping over put()?
    The binding has no bulk write, so every key is a separate `put()`, and one invocation may make at most 1,000 operations to external services such as KV. The job would also need its own retry handling for failed writes. Wrangler or the REST bulk endpoint uploads up to 10,000 pairs per request from one process, which is simpler to run and to retry.
  • In Workers KV, how do you remove a few thousand keys at once?
    Use `wrangler kv bulk delete <filename> --binding FLAGS --remote` with a JSON array of key names, adding `--force` to skip the confirmation prompt in automation, or the REST bulk delete endpoint, which takes up to 10,000 keys per request. Like writes, deletions take time to be seen in locations that cached the old values, and each deleted key is billed.

  • env.FLAGS.put() accepts an array of key-value pairs for bulk writes
  • wrangler kv bulk put writes to production unless --local is passed
  • A bulk upload counts as a single billed write
  • Bulk-written keys are visible everywhere as soon as the command finishes
  • wrangler kv:bulk put is still the correct spelling
  • --preview is how a bulk upload targets the production namespace

Assumes Wrangler 4 (4.149.0 pinned): kv commands default to local mode and need --remote for the real namespace, and the kv: colon syntax no longer parses.