TypeScript で「Object is possibly 'null'」が解消できない

strictNullChecks 有効下では null/undefined を含む型のプロパティアクセスにナローイングが要る。
早期 return / オプショナルチェイン / 非 null アサーションを場面ごとに使い分ける。

#strict #null #narrowing #type-guard #optional-chaining

公開: 2026-05-07更新: 2026-09-11

実行例あり（2026-08-02 に実環境で検証）

要約

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

実行例

実際に上記の手順を node:20（Debian GNU/Linux 12）環境で動かすと、TypeScript 5.9.3 のコンパイラが src/bad.ts(2,1): error TS2531: Object is possibly 'null'. を出力し（終了コード 2）、早期 return およびオプショナルチェイン＋nullish coalescing のいずれの解消策を適用しても終了コード 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-08-02 時点の出力

検証環境

検証日: 2026-08-02
実行環境: node:20

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

よくある原因

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

解決策

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 と組み合わせると型も自然に狭まる。

要約

実行例