miniflare: "compatibility date is invalid" on wrangler dev

TL;DR

Your compatibility_date in wrangler.toml is not a real past date in YYYY-MM-DD format. Set it to a real, published date that is today or earlier (for example 2026-01-15), restart wrangler dev, and the local workerd runtime starts normally. Miniflare refuses future dates, malformed dates, and unparseable strings.

miniflare: "compatibility date is invalid" on wrangler dev

1. Open wrangler.toml and find the compatibility_date line at the top level:

grep compatibility_date wrangler.toml

Expected: exactly one line like compatibility_date = "2026-01-15". If it is empty, missing quotes, or has a typo like "2026-13-40", that is the bug.

1. Fix the value. It must be quoted, YYYY-MM-DD, and not in the future. Pick the most recent Cloudflare compatibility date that is on or before today. Today is 2026-10-08, so any real date on or before today works, e.g. compatibility_date = "2026-09-01".

Expected: the line parses as a quoted date string.

1. Confirm no env block overrides it with a broken value:

grep -n compatibility_date wrangler.toml

Expected: if more than one line appears, every one must be a valid date. An [env.production] override with a bad date will break the run even when the top-level line is fine.

1. Restart wrangler dev:

wrangler dev

Expected: the dev server starts and the banner shows your worker. No compatibility-date message.

1. If the error persists, check whether a stale miniflare install is being used (some setups run miniflare directly). Compare wrangler --version against a fresh install; an old miniflare bundle validated dates more strictly and misreported edge cases.

Expected: after upgrading, the same valid date starts cleanly.

Use this when

• wrangler dev exits immediately with "compatibility date is invalid".
• You just hand-edited compatibility_date and broke the run.
• An agent or script wrote the date programmatically and got the format wrong.

Not for this skill when

• The date is valid but behavior differs from production. That is a compatibility-flags question, not a date-format one.
• The error names a different field (e.g. "invalid compatibility flag"). Fix the flag name instead.
• wrangler dev starts but requests behave oddly. Date validation passed; look elsewhere.

Variant phrasings

• compatibility_date invalid wrangler dev
• miniflare refuses to start bad compatibility date
• wrangler dev compatibility date must be a valid date
• Error: Compatibility date is invalid

Why it happens

compatibility_date pins which workerd runtime behaviors your worker gets, and it must be a real date because workerd maps it to a released runtime build. Miniflare (the local runtime wrangler dev uses) validates the string before boot. A future date, a malformed string, or an unquoted value cannot map to a released build, so miniflare aborts before starting the isolate rather than running with undefined behavior. The usual cause is an agent or template writing a placeholder or tomorrow's date.

Edge cases

• Quoting matters in TOML. compatibility_date = 2026-01-15 (no quotes) is parsed as an expression, not a date string, and fails validation.
• Very old dates (e.g. 2021-01-01) are technically valid but opt you out of years of behavior fixes; prefer a recent date unless you need legacy behavior deliberately.
• The deployed runtime validates the same way. A bad date that somehow survives local dev will fail wrangler deploy too, so fix it at the source.
• Some wrappers pass --compatibility-date as a CLI flag, which overrides the toml. If the toml looks fine, check the launch command.

Provenance

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