Skip to content

Excessive stack depth comparing types

Error message

                Excessive stack depth comparing types
              

Quick summary

TypeScript's type checker exceeded its recursion limit while comparing two types. This usually happens with deeply recursive or self-referential types.

Why this happens

  • Self-referential type definitions

  • Deeply nested generic type instantiations

  • Recursive conditional or mapped types

  • Complex type relationships that create deep comparison chains

Minimal example

✗ Broken code
type Deep<T> = { value: T; next: Deep<T>; }; // unbounded recursion
const x: Deep<number> = complexValue;
✓ Fixed code
type Deep<T, D extends number = 5> = D extends 0 ? never : { value: T; next: Deep<T, D - 1> };

Add a depth parameter to limit the recursion.

How to diagnose

  • Look for recursive type definitions (types that reference themselves)

  • Check for deeply nested generic instantiations

  • Identify the two types being compared in the error

How to fix

  • Break recursive types into simpler non-recursive forms

  • Add a depth limit to recursive types using conditional types

  • Simplify complex generic chains

  • Use type assertions to bypass deep comparison when safe

How to prevent

  • Avoid unbounded recursive types

  • Keep generic nesting reasonable

  • Use explicit type annotations for complex types

Related Resources

Related Glossary

← Back to language