Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Error Codes Worth Knowing

TypeScript error TS2589: type instantiation is excessively deep

TS2589 means TypeScript gave up expanding a recursive type after too many steps. Learn what triggers it, how tail recursion helps, and how to restructure types.

TS2589 reads Type instantiation is excessively deep and possibly infinite. The compiler caps how far it will expand generic and recursive types so that a bad definition cannot hang the editor. When a type needs more levels than the cap allows, it stops and reports this error instead of continuing.

You meet it in type-level programming: counting with tuples, parsing string literals character by character, deeply recursive mapped or conditional types, and generic code over very large unions. It is also triggered by genuinely infinite expansions, where the message is correct and the type is wrong.

TypeScript
type Repeat<N extends number, A extends unknown[] = []> =
  A["length"] extends N ? A : Repeat<N, [...A, 0]>;
type Big = Repeat<2000>;   // error TS2589

Try it

TypeScript Recursion that runs out of depth

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Staying inside the limits

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

The error is reported at the use that starts the instantiation. Causes and remedies:

Cause Remedy
Recursion deeper than the limit (about 1000 for tail-recursive conditional types, much less for non-tail forms) Rewrite as a tail call with an accumulator; reduce the input size.
A type that refers to itself with no base case Add a terminating branch.
Heavy generic constraints that feed back into themselves Simplify the constraint or break the cycle with an interface.
Very large union times very large union Split the work, or avoid distributing over big unions.

Usage notes

  • Tail recursion matters. A conditional type whose recursive call is the whole result of a branch is optimised and can go about 1000 deep. Wrapping the call in a template string, tuple or object makes it non-tail with a far lower limit.
  • Accumulators (the A parameter above) move state into type arguments so the call stays a tail call.
  • Do not fight the limit with // @ts-ignore on the line that uses the type. The type still evaluates to any, which hides further errors.
  • Compile time grows. Types that come close to the limit also slow editors and builds. Measure with tsc --extendedDiagnostics.
  • Real code rarely needs thousands of levels. If a library type triggers it, report the input shape that does so, or pass a simpler type to the generic.
  • Check for an unintended infinite type first, for example a generic default that references the type being defined.