agent loop detected: toggling node_compat on and off after each failed fix attempt

TL;DR

Stop toggling and diagnose which side actually fails: run the worker with the flag on, capture the exact failing import or API, then decide based on evidence. node_compat on and off are not two guesses to alternate; each enables a different module system, and the fix is to satisfy the requirements of one of them deliberately (polyfill, import rewrite, or flag plus code change together).

agent loop detected: toggling node_compat on and off after each failed fix attempt

1. Freeze the flag. Pick the current value and do not change it until the failing dependency is identified.

Expected: the config stops oscillating. One stable state to debug.

1. With the flag ON, deploy to dev and record the exact failure: which import fails, which API is missing, which behavior breaks. Write the full error text to the run log.

Expected: a specific failing symbol (e.g. a node: module that still fails, or a global that changed behavior), not a vague "it broke".

1. With the flag OFF, do the same and record that failure.

Expected: you now have two concrete errors. The real problem is visible: usually one missing node built-in on the OFF side, and one behavior change or unpolyfillable API on the ON side.

1. Choose the side whose failure is fixable in code. If OFF fails only because code imports node:crypto, prefer keeping compat ON and fixing whatever ON breaks (often a global like Buffer behaving differently, fixed by importing node:buffer explicitly). If ON breaks an edge-native API you depend on, keep it OFF and replace the node import with a workerd-native alternative (Web Crypto instead of node:crypto).

Expected: a decision with a reason, written in the run log, plus the accompanying code change. The flag and the code change ship together as one fix.

1. Apply the code change with the flag frozen at the chosen value, then test. Only one variable moves per attempt from here on.

Expected: the specific recorded error is gone. If a new error appears, it is progress, not oscillation.

Use this when

• Consecutive passes flip nodejscompat / nodecompat and the error flips with it.
• The agent's "fix" is always just the flag, never a code change.
• Two different errors alternate in the log.

Not for this skill when

• The flag was changed once deliberately with a code change alongside. That is a normal migration step.
• Only one flag state has ever been tried. Try the other once, with diagnosis, before calling it a loop.
• The failure is unrelated to node APIs (bindings, routes). The flag is a red herring; stop touching it.

Variant phrasings

• agent flips nodejs_compat repeatedly
• node_compat on off loop cloudflare workers
• workers node compatibility toggle infinite retry
• autonomous agent oscillating on compatibility flag

Why it happens

nodejs_compat changes which module system the worker gets: with it, node: built-ins resolve; without it, they do not, and some globals behave differently. An agent that treats the flag as a guess tries ON, hits error B, "fixes" it by trying OFF, hits error A, and ping-pongs forever because neither attempt addresses the underlying dependency. The flag is not a fix; it selects which set of requirements the code must satisfy, and the code has to be changed to satisfy one of them.

Edge cases

• The flag name changed across wrangler versions (nodecompat setting vs nodejscompat compatibility flag). An agent editing the old name while the new one controls behavior will see "no effect" and toggle harder. Check the wrangler version's docs for the current name.
• compatibility_date interacts: newer dates enable more node APIs natively, so the same flag behaves differently across dates. Note the date in the run log alongside the flag.
• Some libraries sniff the runtime and take different code paths under compat. Pinning the library version can matter as much as the flag.
• If the agent cannot decide, the tie-break is: keep compat ON and fix forward, because the ecosystem is moving toward node compatibility, not away from it.

Provenance

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