Cycle dependency shema.js -> iso.js -> schema.js

[justgowa]

Env###

• zod@4.1.12
• Node.js version: 22
• Build tool: webpack with custom cycle deps checker

---

After upgrading to zod v4, the build fails with circular dependency errors:

ERROR in Detected 2 cycles which exceeds configured limit of 0

ERROR in node_modules/zod/v4/classic/iso.js -> node_modules/zod/v4/classic/schemas.js -> node_modules/zod/v4/classic/iso.js

ERROR in node_modules/zod/v4/classic/schemas.js -> node_modules/zod/v4/classic/iso.js -> node_modules/zod/v4/classic/schemas.js

[dosubot]

Hi @justgowa! I'm Dosu and I’m helping the zod team.

This is a known issue in Zod v4: classic/iso.js and classic/schemas.js import each other, creating a circular dependency that some build tools (like Rollup) flag as an error, especially if your cycle limit is set to zero. The cycle is structural—schemas.js uses ISO helpers from iso.js, and iso.js extends types from schemas.js—and has been discussed in GitHub issue #5275.

Zod maintainers are aware that circular dependencies exist in the codebase, and while they are sometimes necessary for API convenience, they can cause bundling problems in strict environments. There’s no official fix yet, but contributors have offered to help refactor and add tests to prevent cycles in the future.

For now, you can try increasing your build tool’s cycle limit or using a bundler that is less strict about cycles. If you need a more targeted workaround, you might be able to patch Zod locally to decouple these modules, but that would require significant refactoring.

If you can share a minimal reproduction or more details about your build setup, it may help diagnose if there’s a workaround specific to your environment. If this answers your question, feel free to close the issue!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}