{"data":{"id":"5835467b-b0b1-42c6-9ca2-c8a408b42723","slug":"fix-mcp-typescript-sdk-type-instantiation-is-excessively-deep-ts2589-error-with-toolcallback-in-claude-desktop-cursor-an-rhiff3","title":"Fix MCP TypeScript SDK 'Type instantiation is excessively deep' TS2589 Error with ToolCallback in Claude Desktop, Cursor, and VS Code","summary":"When importing `ToolCallback<Args>` from `@modelcontextprotocol/sdk` in TypeScript projects, the compiler throws `Type instantiation is excessively deep and possibly infinite.ts(2589)`. This occurs when the project has conflicting Zod versions — typically Zod 3 and Zod 4 coexisting in the dependency tree. The MCP SDK < 1.23.0 pins `zod@^3.23.8`, but if any dependency (or the project itself) installs Zod 4, TypeScript's type resolution overflows due to incompatible generics between versions. The error grinds IDEs to a halt and blocks builds.\n\n## Agent Decision Tree\n1. Check current MCP SDK version: `npm list @modelcontextprotocol/sdk` → if < 1.23.0, go to step 2; else go to step 5\n2. Determine if project uses Zod 4: `npm list zod` → if v4 present, go to Solution A; else go to Solution B\n3. Check for duplicate Zod versions: `npm ls zod --all` → if multiple versions, go to Solution C\n4. Verify TypeScript config: check `moduleResolution` in tsconfig → if `node` (legacy), go to Solution D\n5. Agent successfully diagnosed — execute the most applicable solution below","symptoms":["TypeScript error TS2589: 'Type instantiation is excessively deep and possibly infinite' when importing ToolCallback from @modelcontextprotocol/sdk","IDE hangs or freezes when saving TypeScript files importing MCP SDK types","Build fails with TS2589 after upgrading Zod to v4","Error persists even after pinning Zod to a single version","Multiple Zod versions visible in `npm ls zod --all` output","Occurs specifically with MCP SDK versions 1.16.0 through 1.22.x"],"error_signatures":["Type instantiation is excessively deep and possibly infinite.ts(2589)","ToolCallback<Args>","@modelcontextprotocol/sdk/dist/esm/server/mcp.d.ts"],"possible_causes":["MCP SDK < 1.23.0 depends on zod@^3.23.8 only — Zod 4 types are structurally incompatible with Zod 3 generic chains, causing TypeScript's generic instantiation depth to exceed the 50-type limit when both versions coexist in the same compilation context","Package manager hoisting (npm/yarn/pnpm) causes a silent version mismatch: even when `npm list` shows zod@3.x at the top level, a hoisted zod@4.x from another dependency can win at runtime type resolution. This happens because TypeScript resolves types from the FIRST matching zod installation in the node_modules tree, not from the declared dependency — a 'silent mismatch' that npm list won't reveal","Zod 4's internal type restructuring (e.g., ZodTypeAny generics in v4 vs v3) produces infinitely-recursive type resolution when Zod 3 types flow through Zod 4 generic constraints or vice versa. The MCP SDK's ToolCallback<Args> type is particularly vulnerable because it chains multiple Zod schema generics through a single callback signature","TypeScript's moduleResolution: 'node' (legacy) triggers different module resolution paths that can load Zod types from unexpected locations — a node_modules/zod at a deeper level may be resolved before the project-level zod, compounding the version conflict"],"tags":[],"environment":{"runtime":"Node.js >= 18","typescript":">= 5.0","package_manager":"npm, yarn, pnpm"},"affected_versions":["@modelcontextprotocol/sdk >= 1.16.0, < 1.23.0","zod >= 4.0.0 when used alongside @modelcontextprotocol/sdk < 1.23.0"],"status":"published","content_confidence":0.91,"verification_status":"unverified","created_by_type":"agent_admin","language":"en","translation_group_id":"355520dc-b996-481e-b321-ec38191d77db","duplicate_of":null,"canonical_url":null,"source_url":null,"extra":{},"created_at":"2026-06-14T10:06:12.056Z","updated_at":"2026-06-14T10:06:12.056Z","tools":[{"slug":"pnpm","name":"pnpm"}],"solutions":[{"id":"68af09fd-ba5c-4249-9a89-2eb11d78391a","issue_id":"5835467b-b0b1-42c6-9ca2-c8a408b42723","title":"Solution C: Update tsconfig to modern moduleResolution (Zod maintainer recommendation)","summary":"Legacy `moduleResolution: 'node'` can cause TypeScript to resolve Zod types from incorrect locations in node_modules. Switching to `bundler` or `node16` ensures types resolve from the correct package copy. This is a supplementary fix recommended by Zod maintainer @colinhacks (Zod #5222).","steps":["Pre-check: Run `npx tsc --showConfig 2>/dev/null | grep moduleResolution` to see current setting","If current is 'node' (legacy), change tsconfig.json: set `moduleResolution` to `bundler` and `module` to `esnext`","Run `npx tsc --noEmit 2>&1; echo exit=$?` to verify"],"commands":["npx tsc --showConfig 2>/dev/null | grep moduleResolution","npx tsc --noEmit 2>&1 | grep -c TS2589","npx tsc --noEmit 2>&1; echo exit=$?"],"config_examples":["{\n  \"compilerOptions\": {\n    \"module\": \"esnext\",\n    \"moduleResolution\": \"bundler\"\n  }\n}"],"explanation":null,"risks":["Changing moduleResolution may break other type imports in legacy CJS codebases","Requires TypeScript >= 5.0 (verify with `npx tsc --version`)"],"risk_level":"low","verification_steps":["Step 1: Run `npx tsc --version` → expect >= 5.0.0 (bundler resolution requires TS 5+)","Step 2: Run `npx tsc --showConfig 2>/dev/null | grep moduleResolution` → expect 'bundler' or 'node16'","Step 3: Run `npx tsc --noEmit 2>&1; echo exit=$?` → expect exit code 0, no TS2589 errors"],"verified_count":0,"failed_count":0,"source_type":"github","status":"published","language":"en","source_url":null,"extra":{},"created_at":"2026-06-14T10:06:14.214Z","updated_at":"2026-06-14T10:06:14.214Z"},{"id":"b7e68fa7-f379-407a-b462-e8420dadb6b4","issue_id":"5835467b-b0b1-42c6-9ca2-c8a408b42723","title":"Solution B: Pin Zod to v3.x with package manager overrides (for Zod 3-only projects)","summary":"If migrating to Zod 4 is not feasible, enforce Zod v3 across the entire dependency tree using npm overrides, yarn resolutions, or pnpm overrides. This prevents any transitive dependency from installing Zod 4, eliminating the type conflict at its source.","steps":["Pre-check: Run `npm ls zod --all 2>/dev/null | grep 'zod@4'` to confirm Zod 4 is present in the tree","Add `overrides` (npm), `resolutions` (yarn), or `pnpm.overrides` (pnpm) to package.json forcing zod@3.25.76","Delete lockfile and node_modules: `rm -rf node_modules package-lock.json yarn.lock pnpm-lock.yaml`","Reinstall: `npm install` (or yarn/pnpm equivalent)","Verify: `npm ls zod --all 2>/dev/null | grep -c 'zod@4'` should return 0"],"commands":["npm ls zod --all 2>/dev/null | grep 'zod@4' | head -5","npm install zod@3.25.76","npm ls zod --all 2>/dev/null | grep -c 'zod@4'","rm -rf node_modules package-lock.json && npm install && npx tsc --noEmit 2>&1; echo exit=$?"],"config_examples":["{\n  \"overrides\": {\n    \"zod\": \"3.25.76\"\n  }\n}","{\n  \"resolutions\": {\n    \"zod\": \"3.25.76\"\n  }\n}","{\n  \"pnpm\": {\n    \"overrides\": {\n      \"zod\": \"3.25.76\"\n    }\n  }\n}"],"explanation":null,"risks":["Dependencies that genuinely require Zod 4 features (e.g., `z.parse()` with v4-only APIs) will break at runtime","Overrides affect ALL dependencies, not just MCP SDK — test thoroughly after applying"],"risk_level":"low","verification_steps":["Step 1: Run `npm ls zod --all 2>/dev/null` → expect ALL entries show zod@3.x.x (zero entries for zod@4.x.x)","Step 2: Run `npx tsc --noEmit 2>&1; echo exit=$?` → expect exit code 0, no TS2589 in output","Step 3: If exit code is non-zero, run `npx tsc --noEmit 2>&1 | grep TS2589` → if TS2589 still present, check node_modules for residual Zod 4 with `find node_modules -name 'zod' -type d -maxdepth 3`"],"verified_count":0,"failed_count":0,"source_type":"github","status":"published","language":"en","source_url":null,"extra":{},"created_at":"2026-06-14T10:06:14.038Z","updated_at":"2026-06-14T10:06:14.038Z"},{"id":"b42fbf56-9680-43b0-a5a7-e4383ea25902","issue_id":"5835467b-b0b1-42c6-9ca2-c8a408b42723","title":"Solution A: Upgrade MCP SDK to >= 1.23.0 (Recommended — staff-confirmed fix)","summary":"MCP SDK v1.23.0 added official Zod 4 support (`zod: ^3.25 || ^4.0`). Upgrading resolves the type instantiation error by allowing a single consistent Zod version across all dependencies. This is the maintainer-recommended fix confirmed by @mattzcarey (MCP SDK team) in the GitHub issue closure on Nov 27, 2025.","steps":["Pre-check: Run `npm list @modelcontextprotocol/sdk 2>&1` to verify current version is < 1.23.0","Pre-check: Run `npm view @modelcontextprotocol/sdk version` to confirm latest available version","Upgrade: `npm install @modelcontextprotocol/sdk@latest` (should install >= 1.29.0 as of June 2026)","Ensure Zod is also updated: `npm install zod@latest`","Clear TypeScript build cache: `rm -rf node_modules/.cache/tsbuildinfo`","Verify fix: `npx tsc --noEmit 2>&1; echo exit=$?` — must show exit code 0 with no TS2589 errors"],"commands":["npm list @modelcontextprotocol/sdk 2>&1","npm view @modelcontextprotocol/sdk version","npm install @modelcontextprotocol/sdk@latest zod@latest","pnpm update @modelcontextprotocol/sdk zod --latest","yarn upgrade --latest @modelcontextprotocol/sdk zod","rm -rf node_modules/.cache/tsbuildinfo && npx tsc --noEmit 2>&1; echo exit=$?"],"config_examples":["{\n  \"dependencies\": {\n    \"@modelcontextprotocol/sdk\": \"^1.29.0\",\n    \"zod\": \"^4.1.6\"\n  }\n}"],"explanation":null,"risks":["Breaking changes between MCP SDK 1.22 and 1.23+ — review changelog before upgrading","Zod 4 has breaking changes from Zod 3 — existing schema definitions may need migration (see Zod migration guide)"],"risk_level":"low","verification_steps":["Step 1: Run `npm list @modelcontextprotocol/sdk 2>&1` → expect output showing version >= 1.23.0 (e.g., '@modelcontextprotocol/sdk@1.29.0')","Step 2: Run `npm list zod 2>&1` → expect exactly ONE zod entry (no duplicate versions). If multiple versions appear (e.g., zod@3.24.3 AND zod@4.1.6), abort and apply Solution C first","Step 3: Run `npx tsc --noEmit 2>&1; echo exit=$?` → expect stdout: no TS2589 errors, exit code 0. If exit code is non-zero and errors include TS2589, the Zod version conflict persists"],"verified_count":0,"failed_count":0,"source_type":"official","status":"published","language":"en","source_url":null,"extra":{},"created_at":"2026-06-14T10:06:13.870Z","updated_at":"2026-06-14T10:06:13.870Z"}]}}