What this usually means
Template literal types are a TypeScript feature that allows type-level string concatenation and pattern matching. When you see errors with them, it's usually because the type union you're iterating over is too large (causing infinite recursion), you're not constraining generic parameters to `string`, or you've hit the compiler's recursion depth limit (default 50). The underlying cause is often unbounded string input—like using `string` itself instead of a specific union—or overly complex recursive conditional types that don't reach a base case.
The first ten minutes — establish facts before touching code.
- 1Run `tsc --noEmit --diagnostics` to see where the compiler spends time; look for 'Excessive stack depth' or 'Time' metrics.
- 2Check for `string` as a type argument to a template literal type. Replace `string` with a finite union like `'a' | 'b'` to see if error disappears.
- 3Inspect recursive template literal types: ensure there's a base case that returns a concrete type, not a recursive call.
- 4Use `// @ts-expect-error` to isolate which line triggers the error. Comment out halves of the type to narrow the culprit.
- 5Read the full error stack trace—TypeScript 5.x gives more context. Look for lines with `infer` or template literal expressions.
- 6Check if your TypeScript version is < 4.1; template literal types were introduced in 4.1 and improved in later versions.
The specific files, logs, configs, and dashboards that usually own this bug.
- searchSource files containing `@template` or `infer` clauses with string concatenation
- searchType definitions in `.d.ts` files that use backtick syntax for types
- searchGeneric functions or types that accept type parameters without `extends string` constraint
- searchRecursive conditional types that use template literal patterns
- searchtsconfig.json for `--strict` mode (may affect inference) and `--target` (affects built-in types)
- searchCompiler diagnostics output: `tsc --diagnostics` or `tsc --extendedDiagnostics`
- searchThe `node_modules/typescript/lib/lib.esnext.d.ts` if using ES features
Practical causes, not theory. These are the things you will actually find.
- warningUsing `string` as a type argument instead of a finite union of literal strings
- warningMissing `extends string` constraint on generic type parameters used in template literals
- warningRecursive template literal type that recurses on the full union without narrowing, causing infinite union growth
- warningHitting the compiler's recursion depth limit (default 50) with complex conditional types
- warningUsing template literal types with numeric or boolean types that aren't explicitly converted
- warningIncorrect use of `infer` in template literal patterns—e.g., expecting a single match but multiple matches exist
Concrete fix directions. Pick the one that matches your root cause.
- buildReplace `string` with a specific union of literal strings, or use `string & {}` to narrow if necessary.
- buildAdd `extends string` constraint to generic type parameters used in template literal types.
- buildRefactor recursive template literal types to use distributive conditional types: `T extends string ? ... : never`.
- buildIncrease recursion depth limit via `tsconfig.json` with `--maxNodeModuleJsDepth` but prefer fixing the type.
- buildUse `Capitalize`, `Uncapitalize`, `Uppercase`, `Lowercase` built-in helpers instead of manual recursion where possible.
- buildFor complex parsing, use type-level recursion with a counter or accumulator to ensure termination.
A fix you cannot prove is a guess. Close the loop.
- verifiedCompile with `tsc --noEmit` and confirm zero errors.
- verifiedVerify IntelliSense shows the correct union type instead of 'any' or 'never'.
- verifiedTest edge cases: empty string `''`, single character, long strings (>50 chars) to ensure no recursion limit hit.
- verifiedUse `type X = YourType<'test'>` and hover to see resolved type in VSCode.
- verifiedRun `tsc --diagnostics --noEmit` and confirm no excessive stack depth warnings.
- verifiedWrite unit tests with `expectType<Expected, Actual>` using `@type-challenges/utils` or similar.
Things that make this bug worse or harder to find.
- warningAssuming template literal types work with any type—they only work with string, number, bigint, boolean, null, undefined.
- warningForgetting to constrain generic parameters—`<T extends string>` is required.
- warningUsing template literal types with `any` or `never`—they produce unexpected results.
- warningIgnoring recursion depth: the compiler has a limit, and deep recursion (e.g., parsing 100-character strings) will fail.
- warningMixing template literal types with union types carelessly—every union member expands the type combinatorially.
- warningAssuming order of evaluation in template literal types—it's left-to-right, but conditional types can reorder.
Infinite union from template literal type on user input
Timeline
- 09:15Deploy pipeline fails with 'Type instantiation is excessively deep and possibly infinite' on CI
- 09:20Local build succeeds; only fails on CI with different Node version (16 vs 18)
- 09:35Identify the error comes from a newly added template literal type: `type EventName<T> = `on${T}`
- 09:45Check the type argument—it's `string` passed from a generic function without constraint
- 10:00Add `extends string` constraint—error persists but now shows 'Type instantiation is overly complex'
- 10:15Realize the function accepts any string, but the template literal expands to infinite union
- 10:30Fix: change function signature to accept a finite union of possible event names
- 10:35Pass CI; deploy succeeds
I was pushing a new feature that added typed event listeners to our UI component library. The idea was simple: take a string and convert it to an event name using `on${T}`. The type looked elegant, and it worked in our small test suite with a few literal strings.
But when the CI pipeline ran, it failed with a 'Type instantiation is excessively deep' error on a completely unrelated file. The build took 5 minutes before timing out. Locally, it compiled fine because I had fewer type checks. The issue was that the generic function didn't constrain `T`—it accepted `string`, and when combined with other types in the codebase, the compiler tried to expand `on${string}` which is infinite.
Adding `extends string` helped a bit but didn't fix the root cause: the function was designed to accept any string, but template literal types require finite unions. I refactored the API to accept a predefined set of events, and the error vanished. The lesson: template literal types are powerful but demand finite input—`string` is a trap.
Root cause
Template literal type `on${T}` with `T = string` creates an infinite union of all possible strings, causing compiler recursion limit.
The fix
Changed generic parameter to extend a finite union of literal strings: `<T extends 'click' | 'hover' | 'focus'>`.
The lesson
Always constrain template literal type parameters to finite literal unions; never pass `string` directly.
Template literal types, introduced in TypeScript 4.1, allow you to construct new string literal types by concatenating existing ones. When you write `type EventName<T> = `on${T}`` and pass `string` as `T`, TypeScript attempts to create a union of all possible strings prefixed with 'on'. Since `string` is an infinite set, the compiler cannot enumerate it, leading to error 2589 or infinite recursion.
The fix is to ensure `T` is a finite union of literal strings. Use a discriminated union or an enum. If you truly need to accept any string, avoid template literal types and use a runtime check with a branded type instead.
TypeScript has a default recursion depth limit of 50 for type instantiations. Recursive template literal types, such as a type that strips characters from a string one by one, can hit this limit if the input string is longer than 50 characters. The error 'Type instantiation is excessively deep' is the result.
To avoid this, refactor recursion to use tail-recursion or to process multiple characters per step. Alternatively, use built-in helper types like `Uppercase` or `Capitalize` that are implemented natively and don't count toward recursion depth. As a last resort, increase the limit with `--maxNodeModuleJsDepth` in tsconfig, but this is a band-aid.
Template literal types often fail to infer correctly when used with generic functions. For example, a function `function on<T extends string>(event: `on${T}`)` may infer `T` as `string` instead of a literal because the template literal type is too general. This happens because TypeScript's inference algorithm works best with simple literal types.
To force inference, use a helper type that extracts the prefix/suffix: `type ExtractEvent<S> = S extends `on${infer T}` ? T : never`. Then use `ExtractEvent<typeof event>` to get the exact literal. Another approach is to use a variant with a default type parameter to guide inference.
Error TS2344 occurs when a type used in a template literal is not a valid type for such operation. Template literal types only accept `string | number | bigint | boolean | null | undefined`. If you pass an object or array, you get this error.
Check that all type parameters in template literal expressions are constrained to `string` or a union of primitives. Use `T extends string | number | boolean` if needed. Also, note that `null` and `undefined` are allowed but produce the string 'null' or 'undefined'.
The `infer` keyword inside template literal types enables parsing of string patterns. For example, `type GetRoute<S> = S extends `/${infer Path}` ? Path : never` extracts the path from a route string. However, it's easy to create ambiguous patterns where multiple `infer` positions compete.
Be explicit: use exact string literals in patterns and avoid overlapping matches. Test with known inputs. If you get `never`, the pattern didn't match—check for missing characters or incorrect case.
Frequently asked questions
Why does my template literal type work with literal strings but fail with `string`?
Template literal types require finite unions to expand. `string` is an infinite set, so the compiler cannot create a union of all possible string combinations. Always use a finite union of literals or constrain the generic parameter to a specific set.
How do I fix 'Type instantiation is excessively deep and possibly infinite'?
This usually means a recursive type is not terminating or the input is too long. Ensure your recursion has a base case that returns a concrete type, and avoid processing strings longer than 50 characters per recursion. If necessary, increase the recursion limit with `--maxNodeModuleJsDepth` but prefer refactoring.
Can I use template literal types with numbers?
Yes, numbers are allowed and are converted to their string representation. However, the result is a string literal type, not a number. For example, `type Num = `${42}`` results in `'42'`. For arithmetic, you'll need recursive conditional types that manipulate string representations.
Why does TypeScript infer `any` instead of the expected literal type?
This happens when the template literal type is too complex for inference, or when the generic parameter is not constrained properly. Use an explicit constraint like `<T extends 'a' | 'b'>` to guide inference. Alternatively, provide a default type or use a helper extraction type.
How can I parse a string with multiple parts using template literal types?
Use multiple `infer` positions in a pattern, e.g., `type Parse<S> = S extends `${infer A}-${infer B}` ? [A, B] : never`. Each `infer` captures a substring. Be careful with greedy vs. non-greedy matching—TypeScript's inference is left-to-right and as short as possible.