What does TypeScript's error "Type instantiation is excessively deep and possibly infinite" mean, and what do you change in a recursive conditional type to get past it?

## What the error actually reports `Type instantiation is excessively deep and possibly infinite` (TS2589) is a **budget** error, not a correctness error. Type-level recursion in TypeScript is Turing-complete in practice, so the checker cannot decide whether your type terminates; instead it counts how deep it has gone instantiating generic types and stops at a fixed ceiling. Two very different situations produce the same message: 1. **Genuinely infinite** — the recursion has no base case, or the base case is unreachable. Example: a helper that recurses into `T[K]` for a self-referencing `interface Node { parent: Node }`. 2. **Merely deep** — the recursion terminates, but not within the budget. Building a 200-element tuple, joining a long string union, or splitting a long path one character at a time. The cure is different for each, so diagnose before you optimise. When the error fires, the offending instantiation does not simply disappear: the compiler substitutes an error type that behaves like `any` for that position. Everything downstream still compiles, which is why these failures often hide for a while — the red squiggle is in one file, the lost type safety is in another. ## Base case first Every recursive conditional type needs a terminating branch that the recursion can actually reach: ```typescript type Length<T extends readonly unknown[], Acc extends 1[] = []> = T extends readonly [unknown, ...infer Rest] ? Length<Rest, [...Acc, 1]> : Acc["length"]; ``` The false branch is the base case, reached when the tuple is empty. A classic bug is testing something that never becomes false — for instance recursing while `T extends object` over a type whose property loops back to itself. ## Tail position and tail-recursion elimination TypeScript 4.5 added **tail-recursion elimination on conditional types**. It applies when the recursive reference is the *whole* result of a branch — nothing wraps it. The compiler then loops instead of nesting instantiations, and the effective iteration ceiling rises to roughly a thousand. A non-tail-recursive `Join` looks like this: ```typescript // NOT tail-recursive: the recursive call is embedded in a template literal type Join<T extends readonly string[], D extends string> = T extends readonly [infer F extends string, ...infer R extends readonly string[]] ? R["length"] extends 0 ? F : `${F}${D}${Join<R, D>}` : ""; ``` Each step must remember "prepend `${F}${D}` to whatever comes back", so the instantiations nest. Rewriting with an accumulator moves that work to the way *in*: ```typescript // tail-recursive: the recursive call IS the branch result type Join< T extends readonly string[], D extends string, Acc extends string = "" > = T extends readonly [infer F extends string, ...infer R extends readonly string[]] ? Join<R, D, Acc extends "" ? F : `${Acc}${D}${F}`> : Acc; ``` Nothing wraps `Join<...>` in the true branch, so it qualifies. (The `infer F extends string` form — an inference site with a constraint — requires TypeScript 4.8 or later; before that you write `infer F` and add `F extends string` tests or an `& string` intersection.) This accumulator rewrite is the single highest-value trick for these errors, and it is what an interviewer is usually fishing for. ## Capping depth deliberately When the input can be arbitrarily deep or cyclic, no rewrite saves you — you have to decide how deep is enough: ```typescript type Prev = [never, 0, 1, 2, 3, 4, 5]; type DeepKeys<T, D extends number = 5> = [D] extends [never] ? never : T extends object ? { [K in keyof T & string]: K | DeepKeys<T[K], Prev[D]> }[keyof T & string] : never; ``` The `Prev` tuple is a decrement operator: indexing it walks the counter down, and reaching `never` stops the recursion. `[D] extends [never]` is wrapped in tuples on purpose so the conditional does not distribute. Five levels is almost always enough for real data, and the type stays fast. ## Other levers - **Shrink the work per step.** Splitting a string one character at a time is enormously more expensive than splitting on a delimiter. Recurse over the coarsest unit that answers the question. - **Avoid distributing over huge unions.** A naked type parameter in a conditional distributes; combined with recursion this multiplies instantiations. Wrap in a one-tuple (`[T] extends [U]`) when you do not want distribution. - **Cache intermediate results in type parameters** rather than recomputing the same instantiation in several branches. - **Constrain the entry point.** Accepting `string` where you meant a small literal union invites the checker to explore far more instantiations than you intended. ## What not to do There is no compiler option that raises the recursion limit — the ceiling is fixed in the checker, so reaching for tsconfig is a wrong turn. Suppressing the error with a comment is worse than useless: the instantiation still fails, the type still degrades, and now nothing tells you. And an assertion at the use site papers over a type the compiler never computed. Either make the recursion cheap enough to finish, or bound it and accept a shallower type.