Pit record
MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE
Using MCP SDK tool types (e.g. ToolCallback<Args>) with Zod can trigger 'Type instantiation is excessively deep and possibly infinite ts(2589)' and freeze the TypeScript language server. Fix on the Zod/tsconfig side: single Zod version, modern moduleResolution (not legacy 'node'), and a Zod release with the fix (4.1.6).
Markdown mirror | Canonical source
Fast answer
Problem: Type instantiation is excessively deep and possibly infinite.ts(2589) on lines referencing SDK tool types
Root cause: Deep generic instantiation in Zod's types as consumed by the SDK's tool typings.
Fix first: Ensure a single Zod version is installed; duplicates are a common trigger.
Verify: Reopen the project and reference SDK tool types after the change.
Queries this answers
- Type instantiation is excessively deep when importing ToolCallback Zod author recommends single Zod version + modern moduleResolution; fixed in Zod 4.1.6
- Type instantiation is excessively deep when importing ToolCallback (Zod author recommends single Zod version + modern moduleResolution; fixed in Zod 4.1.6) fix
- Type instantiation is excessively deep when importing ToolCallback (Zod author recommends single Zod version + modern moduleResolution; fixed in Zod 4.1.6) root cause
- MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE
- MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE fix
- MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE root cause
- how to fix MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE
- mcp-server type instantiation excessively deep ts2589 freezes ide
Record metadata
| Status | verified |
|---|---|
| Confidence | medium |
| Created | 2026-06-21 |
| Updated | 2026-06-21 |
| Last verified | 2026-06-21 |
| Affected tools | mcp-server, typescript-sdk |
| Tags | mcp, typescript-sdk, zod, typescript, tsconfig, type-error, ide |
Common search queries
- mcp-ts-sdk-type-instantiation-excessively-deep
- mcp ts sdk type instantiation excessively deep
- MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE
- MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE fix
- MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE root cause
- typescript-sdk
- typescript
- tsconfig
- type-error
- mcp-server
- Type instantiation is excessively deep and possibly infinite.ts(2589) on lines referencing SDK tool types
- the TypeScript server in Cursor/VS Code hangs and saving files stalls
Symptoms
- Type instantiation is excessively deep and possibly infinite.ts(2589) on lines referencing SDK tool types
- the TypeScript server in Cursor/VS Code hangs and saving files stalls
- it appears intermittently; @ts-ignore silences the error but not the slowdown
Environment
| language | TypeScript |
|---|---|
| constraints | Zod-typed tool definitions, possibly multiple Zod versions, legacy moduleResolution 'node', SDK >= 1.16.0 reported |
Root cause
- Deep generic instantiation in Zod's types as consumed by the SDK's tool typings.
- Worsened by multiple resolved Zod versions, a legacy moduleResolution: 'node' tsconfig, and certain SDK versions (reported from >=1.16.0).
Fix
Ensure a single Zod version is installed; duplicates are a common trigger.
npm ls zodUpdate tsconfig to a modern module/moduleResolution (e.g. 'bundler' or 'nodenext') instead of legacy 'node'.
Recommended by the Zod author for this class of deep-instantiation error.
If on Zod 4, upgrade to a release with the fix (reported fixed in Zod 4.1.6); on Zod 3 the tsconfig change is the main lever.
As a stopgap, pin a known-good combination such as SDK 1.12.1 with zod 3.25.49.
Verification
Reopen the project and reference SDK tool types after the change.
Expected: No ts(2589) error and the TypeScript server responds normally (no hang on save).
Workarounds
- Pin a known-good SDK + Zod pair until you can update tsconfig/Zod.
Anti-patterns
- Suppressing with @ts-ignore and ignoring the language-server slowdown.
- Leaving two Zod versions in the dependency tree.
Sources
No matching fix?
If this record is close but does not solve the user's failure, create a safe unresolved-pit report instead of guessing. Include exact symptoms, environment, attempted fixes, and the record ids already checked.