Wrangler Config Doctor

Find common Wrangler configuration mistakes before you deploy. An offline v0.1 beta with a CLI and one local MCP tool. Independent software by Valen Systems; not affiliated with Cloudflare.

Try it

Install Node.js 22.13 or newer, extract the ZIP, then run:

node wrangler-config-doctor.mjs --help
node wrangler-config-doctor.mjs check examples/wrangler.jsonc

For your own project, run from its directory:

node /path/to/wrangler-config-doctor.mjs check wrangler.jsonc
node /path/to/wrangler-config-doctor.mjs check wrangler.toml --env staging --strict

Paths are relative to the current directory. Select exactly wrangler.toml, wrangler.json, or wrangler.jsonc, optionally in a subdirectory. The tool reads only that file. It does not discover parent configurations, resolve $schema, load environment files, execute build commands, contact Cloudflare, or change files.

What it checks

WCD004 and WCD008 are warnings. A missing assets directory is also a warning because build plugins can supply it. Routes and triggers inherit; bindings and vars do not. Migration operations are compared within each migration, so creating a class in one migration and deleting it later is valid.

JSON output is deterministic. Diagnostics contain fixed messages and schema paths, with no config values, binding names, routes, or secret keys. The input path, selected environment, byte count, and input SHA-256 are included. Treat receipts as private if those identifiers are sensitive; the hash is an integrity check, not encryption.

Exit codes: 0 passes the selected policy; 2 has errors (or warnings with --strict); 64 is invalid input; 70 is an internal failure. Input failures produce a fixed error code on stderr and no receipt. Parse errors and duplicate keys fail before analysis.

Local MCP

{
  "mcpServers": {
    "wrangler-config-doctor": {
      "command": "node",
      "args": ["/path/to/wrangler-config-doctor.mjs", "mcp", "--root", "/path/to/project"]
    }
  }
}

The read-only wrangler_config_check tool accepts configPath, optional environment, and optional strict. Paths stay beneath the startup root. The root and config path must not be symlinks. Use a stable project directory; v0.1 is not a sandbox against another local process concurrently replacing directories.

Scope

These eight checks are advisory, not complete Wrangler schema validation or proof that a deployment will succeed. Unknown properties are ignored. Supported bindings: KV, R2, D1, Vectorize, Hyperdrive, services, Analytics Engine, mTLS, dispatch namespaces, Workflows, Pipelines, Secrets Store, AI, browser, images, version metadata, Durable Objects, queue producers, email, assets, and vars. Other binding categories are outside v0.1 coverage.

Input is capped at 1 MiB, 64 environments, nesting depth 64, 50,000 parsed values, and 256 inspected binding/migration entries. Exceeding a limit fails the analysis. The assets directory is checked for configuration shape, not opened or traversed. TOML date/time values are unsupported; write compatibility dates as quoted strings. Windows execution has not yet been tested.

Rule provenance is pinned in rule-pack.json: Wrangler 4.130.0, its upstream commit, and the configuration schema hash. Full schema coverage and broader platform testing can follow after feedback.

Build from source

npm ci --ignore-scripts
npm test
npm run build

Builds use Node, esbuild, and the host's zip command. The ZIP requires only Node at runtime, without a dependency install. Original code is MIT licensed; the distribution includes THIRD_PARTY_NOTICES.md and exact upstream license texts.