できない.dev

TypeScript「Type instantiation is excessively deep and possibly infinite」の原因と直し方

Type instantiation is excessively deep は、再帰型に終端条件を入れ、中間型を type で固定すれば通る。
tsc が条件型の再帰展開を諦めたときに出る。

公開: 更新:

症状できない · exit 2
npx tsc --noEmit bad.ts
bad.ts(3,12): error TS2589: Type instantiation is excessively deep and possibly infinite.
解決後できた · exit 0
npx tsc --noEmit good.ts

2026-10-30 に node:20(TypeScript 5.9.3 / Node.js 20.20.2) で実際に打って取った出力。検証環境の詳細

要約

Type instantiation is excessively deep and possibly infinite. は、tsc が 条件型の再帰展開を深掘りしきれずに諦めた ときに出る。
終端条件付きカウンタを再帰型に挿す、中間型を type で固定する、[T] extends [U] でユニオン分配を抑える、の 3 系統で大半は解消する。
最後の手段として TypeScript を上げて再帰最適化に頼る。

実行例

node:20 のコンテナで TypeScript 5.9.3 を使うと、終端条件が 500 の型は TS2589 で終了コード 2 になった。
終端条件を 5 に収めた型は、同じ tsc で終了コード 0 になった。

Version 5.9.3
$ npx tsc --noEmit bad.ts
bad.ts(3,12): error TS2589: Type instantiation is excessively deep and possibly infinite.
$ echo $?
2
$ npx tsc --noEmit good.ts
$ echo $?
0

— 2026-10-30 時点の出力

検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-10-30 検証(ほか 2 件)
検証日
実行環境
node:20 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5
  • TypeScript 5.9.3

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. 終端条件付きの再帰

type Depth = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8];
type Flatten<T, D extends number = 5> =
  D extends 0
    ? T
    : T extends ReadonlyArray<infer U>
      ? Flatten<U, Depth[D] extends number ? Depth[D] : 0>
      : T;

カウンタ型引数を使って 必ず終わる 再帰にする(条件型の公式ドキュメント(新しいタブで開く))。

2. 中間型を固定する

type Step1<T> = /* 重い計算 */ never;
type Step2<T> = /* 別計算 */ never;
type Result<T> = Step2<Step1<T>>;

ネストを浅くすると tsc が同じ部分式を都度再評価しなくなる。

3. ユニオン分配を抑制する

type IsExactArray<T> = [T] extends [readonly unknown[]] ? true : false;

[T] extends [U] のタプル包み形にするとユニオンの分配が止まり、再帰の組合せ数が一気に減る。

4. TypeScript を更新する

npm install -D typescript@latest

TypeScript Performance Wiki(新しいタブで開く) でも、再帰型の最適化はバージョンごとに改善が続いている。
コード側で組合せを減らすのが筋だが、5.x 系で素直に通るケースは少なくない。

よくある原因

  1. 再帰の終端条件が欠けている。
    再帰条件型 Recur<T> が T を縮約せず、同じ形のまま自身を呼び続ける。
  2. マップ型を大きなユニオンと組み合わせている。
    { [K in keyof T]: ... } をネストしたまま、T が深くて広いユニオンになっている。
  3. ユニオンが自動で分配されている。
    条件型は引数がユニオンだと自動で分配されるので、再帰中に分配されると組合せが指数的に膨らむ。
  4. TypeScript が古い。
    4.0 前後では再帰条件型の最適化が限定的で、5.x なら通る型でも落ちることがある。