できない.dev

TypeScript「Object is possibly 'null'」の原因と直し方

Object is possibly 'null' は、早期 return や ?. で null を除けば消える。
strictNullChecks 下でナローイングせずにアクセスすると出る。
! は最後の手段にする。

公開: 更新:

症状できない · exit 2
npx tsc
src/bad.ts(2,1): error TS2531: Object is possibly 'null'.
解決後できた · exit 0
npx tsc

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

要約

Object is possibly 'null'. は strictNullChecks 下で null / undefined を含む型 に対し、ナローイングなしでプロパティアクセスしたときに出る。
早期 return で型を狭める、?. で安全アクセス、最後の手段として ! を使う、の 3 系統を場面で使い分ければ素直に解消する。

実行例

node:20 のコンテナで TypeScript 5.9.3 の tsc を strict 有効で回すと、null の可能性がある値に触れた src/bad.ts(2,1) で TS2531: Object is possibly 'null'. が出て終了コード 2 になった。
早期 return で書き直した版と、オプショナルチェイン(?.)と ?? で書き直した版は、どちらも終了コード 0 で通った。

Version 5.9.3
$ npx tsc
src/bad.ts(2,1): error TS2531: Object is possibly 'null'.
$ echo $?
2
$ npx tsc
$ echo $?
0
$ npx tsc
$ echo $?
0

— 2026-10-26 時点の出力

検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-10-26 検証(ほか 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. 早期 return でナローイング

const el = document.querySelector(".target");
if (!el) return;
el.classList.add("active");   // ここでは Element 型に絞られる

公式の Narrowing ドキュメント(新しいタブで開く) のとおり、if (!x) return の後ろでは型が狭まる。

2. オプショナルチェインと nullish coalescing

const text = el?.textContent ?? "";
user.profile?.name?.toUpperCase();

?. は途中で null / undefined に当たれば全体を undefined にする。
?? で既定値を埋めれば後段の処理がそのまま書ける。

3. 非 null アサーション(最終手段)

const root = document.getElementById("root")!;   // null では無いと断言

呼ぶ側が存在を保証できる場面に限って使う。
多用すると本来の null チェックを蝕むため、レビューで歯止めをかける。

4. 型ガード関数で再利用する

function isNonNull<T>(v: T | null | undefined): v is T {
  return v !== null && v !== undefined;
}
 
const items = [1, null, 2, undefined].filter(isNonNull);
//    ^? number[]

v is T で書く述語型は複数箇所で同じ条件を再利用するときに便利だ。
Array#filter と組み合わせると型も自然に狭まる。

よくある原因

  1. strictNullChecks が有効になっている。
    strict: true で連動し、null / undefined が型に明示的に含まれる(tsconfig 公式(新しいタブで開く))。
  2. DOM API の戻り値が null を含む。
    document.querySelector('.x') は Element | null を返し、canvas.getContext('2d') の戻り値も null を含む。
  3. ライブラリ API の値が undefined を含む。
    useRef<HTMLDivElement>(null) の .current や Map<K, V>#get の型は T | undefined になる。
  4. 判定が漏れている。
    一度 null チェックしても、別の if スコープに入るとナローイングが効かなくなり、再度警告が出る。