TypeScript ‘Object is possibly ‘null’ or ‘undefined’.’ の原因と解決方法

Object is possibly ‘null’ or ‘undefined’. とは

このエラーは、TypeScriptの厳格なnullチェックが有効な環境で、変数がnullまたはundefinedである可能性があるにもかかわらず、その値が非null/非undefinedを要求するコンテキストで使用された場合に発生します。これは、ランタイムエラーを防ぐためのTypeScriptの重要な安全機能です。

エラーの発生パターン

このエラーは主に以下のようなケースで発生します。

パターン1: プロパティへの直接アクセス（nullチェックなし）

let user: { name: string } | null = null;
console.log(user.name); // Error: Object is possibly 'null'.

userがnullである可能性があるにもかかわらず、そのプロパティnameに直接アクセスしようとしているため、TypeScriptがエラーを報告します。アクセス前にnullチェックを行う必要があります。

let user: { name: string } | null = null;
if (user) {
  console.log(user.name);
} else {
  console.log("User is null.");
}

パターン2: Optional chainingを使用しない値の代入

let data: { value?: string } = {};
let result: string = data.value; // Error: Type 'string | undefined' is not assignable to type 'string'.

data.valueはundefinedである可能性があるため、string型が期待されるresultに直接代入しようとするとエラーになります。デフォルト値を提供するか、undefinedチェックが必要です。

let data: { value?: string } = {};
let result: string = data.value ?? 'default'; // Nullish coalescing operatorでデフォルト値を設定
console.log(result);

パターン3: 関数パラメータや戻り値がnull/undefinedの可能性を考慮しない

function getName(user: { name: string } | null): string {
  return user.name; // Error: Object is possibly 'null'.
}

関数getNameの引数userがnullである可能性があるにもかかわらず、戻り値がstringと宣言されており、内部でuser.nameに直接アクセスしているためエラーになります。引数のnullチェックまたは戻り値の型変更が必要です。

function getName(user: { name: string } | null): string | null {
  return user ? user.name : null;
}

let userName = getName(null);
if (userName) {
  console.log(userName);
}

根本原因の特定方法

このエラーが発生した箇所で、変数の型と現在の値をデバッガで確認してください。特に、nullやundefinedが代入されている可能性のある場所を特定することが重要です。

let potentiallyNull: string | null = Math.random() > 0.5 ? "Hello" : null;

if (potentiallyNull === null) {
  console.log("Value is null here.");
} else {
  console.log("Value is: ", potentiallyNull);
}

防止策とベストプラクティス

TypeScriptの厳格なnullチェック(strictNullChecks: true)を有効にし、Optional Chaining (?.) や Nullish Coalescing (??) 演算子を積極的に使用することで、この種のエラーを未然に防げます。

interface User { name: string; address?: { street: string }; }

function getUserAddress(user?: User): string {
  // Optional ChainingとNullish Coalescingを使用
  return user?.address?.street ?? 'Unknown'; 
}

const user1: User = { name: "Alice", address: { street: "Main St" } };
const user2: User = { name: "Bob" };
const user3: User | undefined = undefined;

console.log(getUserAddress(user1)); // Main St
console.log(getUserAddress(user2)); // Unknown
console.log(getUserAddress(user3)); // Unknown

よくある質問（FAQ）