wrangler dev: hot reload broken, not picking up wrangler.toml changes

TL;DR

Restart wrangler dev after editing wrangler.toml. workerd hot reload recompiles your JS/TS on save but does NOT re-apply config changes (bindings, vars, compatibility date, cron triggers) to a running dev session. Kill it, run wrangler dev again, and confirm the new config loaded with wrangler dev --verbose or by reading back a var in the browser.

wrangler dev: hot reload broken, not picking up wrangler.toml changes

1. Stop wrangler dev completely. Ctrl-C, then confirm nothing is still bound:

wrangler dev

Expected: the process exits. If your terminal says the port is still in use, kill the stale process first or pass a new port.

1. Sanity-check the edited file before relaunching:

npx wrangler deploy --dry-run

Expected: the dry run prints the parsed config (name, bindings, vars). If it errors, the toml edit itself was malformed, not the reload.

1. Relaunch with verbose output and watch the startup block:

wrangler dev --verbose

Expected: the startup banner lists your bindings and vars, including the values you just changed. If they are missing here, the edit went to the wrong file or wrong section.

1. Verify at runtime by hitting an endpoint that echoes the changed value back (e.g. a [vars] value or binding name you just edited).

Expected: the response shows the new value. Old value means you are testing against a different worker (deployed URL vs local URL is the usual mix-up).

1. If a KV or D1 binding changed, also check whether local persistence matters: bindings like KV need --persist-to (or a configured persist dir) to behave across restarts.

Expected: data survives the restart cycle you will now always be doing after config edits.

Use this when

• You edited [vars], [kvnamespaces], [d1databases], [r2_buckets], [env] sections and wrangler dev keeps the old values.
• You changed compatibilitydate or compatibilityflags and behavior did not shift.
• Hot reload clearly works for .ts/.js edits (rebuild messages appear) but config edits seem invisible.
• Multiple envs exist and you edited the top level but are running with --env SOME_ENV, which overrides those keys.

Not for this skill when

• Code changes are not hot reloading either. That is a file-watcher issue (often bind mounts or networked filesystems), not config handling.
• The dev server shows the new config but the deployed worker does not. That is a deploy/publish question, run wrangler deploy.
• wrangler.toml edits are picked up but the values are wrong. That is a wrong-value bug in the file, inspect the file.

Variant phrasings

• wrangler dev ignores changes to wrangler.toml
• why does wrangler dev need a restart for config changes
• wrangler dev binding changes not applied without restart
• compatibility_date change not reflected in wrangler dev

Why it happens

wrangler dev has two reload paths. Code changes trigger a fast recompile in workerd and the new isolate swaps in. Config is read once at startup to build the workerd runtime configuration (binding registrations, environment values, flags). There is no live re-read of the config file, so a long-running dev session keeps serving the startup snapshot no matter what you edit. This is by design, not a bug.

Edge cases

• Running with --env means the [env.MY_ENV] block overrides top-level keys. Editing the top level while running --env staging looks exactly like hot reload failing. Move the edit into the right env block.
• wrangler.jsonc users hit the same behavior. The rule applies to either config format.
• Secrets set via wrangler secret put also need a restart of wrangler dev to appear in the local session.
• Some CI-style dev wrappers restart the port but reuse a cached config path. Verify which config file wrangler printed in the startup banner with --verbose.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_8JEBhiTM3wgtRYlH5UhBnA