agent parser broke on miniflare error output format change

TL;DR: Stop regex-matching miniflare's rendered error text and read the structured error fields (name, code, message) from the caught rejection instead. Miniflare's error rendering changed across v2, v3, and the workerd-based v4, so exact-text matchers break on every upgrade while the fields stay stable.

agent parser broke on miniflare error output format change

Steps

1. Pin the miniflare version in devDependencies and record it with npx miniflare --version. Expected: one version number you can tie any parser failure to.

2. Replace exact-text matching with structural matching: catch the rejection from the request handler (dispatchFetch or the equivalent entry point) and read error.name, error.code, and error.message as fields. Expected: the parser extracts the error class even when the rendered text changes shape.

3. Keep one golden test: trigger a known error (e.g. a missing KV binding read) and assert the parser extracts its code. Expected: upgrading miniflare turns this test red before production parsers break.

4. When a break happens, diff the rendered output of the golden error between the old and new miniflare version. Expected: you see exactly which line of the format moved, and you update one matcher instead of rewriting the parser.

5. Document the miniflare version range the parser is verified against in the runbook. Expected: the next agent knows which versions are safe without re-discovering it.

Use this when

• An agent parses miniflare stderr or thrown errors and broke after a miniflare upgrade
• Error classification depends on matching rendered stack text
• Local dev uses miniflare directly rather than through wrangler dev

Not for this skill when

• The error comes from deployed workerd rather than local miniflare
• Miniflare fails to start at all (a startup problem, not a parsing problem)
• You need the full stack text for human display rather than machine parsing

Variant phrasings

• miniflare error format changed, parser no longer matches
• agent fails to classify miniflare v4 errors
• miniflare stack trace format different after upgrade
• workerd error codes not parsed from miniflare output

Why it happens

Miniflare v4 is a thin layer over workerd, while v2/v3 rendered their own error text, so prefixes, stack formatting, and how error codes surface all moved between majors. Parsers written against one version's exact wording have nothing stable to hold onto, while the underlying Error object's name, code, and message fields survive the rendering changes.

Edge cases

• Some workerd errors surface only as message text with no distinct code; keep a small allowlist of those messages as a fallback.
• Miniflare can wrap the original error in an outer error; unwrap cause chains before classifying.
• wrangler dev embeds its own miniflare version, which may differ from the standalone one you pinned; check both.
• Snapshot tests on full rendered output are brittle by design; assert on extracted fields, not on the raw text.

Provenance

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