TypeScript「Property does not exist on type」の原因と直し方
Property 'x' does not exist on type 'Y' は、型定義を広げるか型ガードで絞り込めば消える。
実装は知っているのに型が知らないプロパティにアクセスすると出る。
公開: 更新:
npx tsc src/bad.ts(3,18): error TS2339: Property 'email' does not exist on type '{ id: string; name: string; }'.
npx tsc
2026-10-27 に node:20(TypeScript 5.9.3 / Node.js 20.20.2) で実際に打って取った出力。検証環境の詳細
要約
Property 'x' does not exist on type 'Y'. は 実装が知っているが型定義が知らないプロパティ にアクセスしたときに出る。
「型がそもそも狭い」「ユニオン型で絞り込んでいない」「宣言が無い」のどれかを切り分け、対応する書き方を選ぶ。
実行例
node:20 環境で上記の手順を動かすと、email プロパティを持たない型への参照をコンパイラが error TS2339 として検出した。interface で正しく宣言し直すと、終了コードは 0 に変わった。
Version 5.9.3$ npx tsc
src/bad.ts(3,18): error TS2339: Property 'email' does not exist on type '{ id: string; name: string; }'.
$ echo $?
2$ npx tsc
$ echo $?
0— 2026-10-27 時点の出力
検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-10-27 検証(ほか 2 件)
- 検証日
- 実行環境
node:20Debian 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. 型を明示する
interface User {
id: string;
name: string;
email: string;
}
async function fetchUser(): Promise<User> {
const res = await fetch("/api/me");
return (await res.json()) as User;
}Object Types 公式ハンドブック(新しいタブで開く) のとおり、interface か type で必要なプロパティを宣言する。
受け取った値はまず unknown に置き、型ガードで絞り込むとより安全である。
2. ユニオン型は絞り込んでから読む
type Shape =
| { kind: "circle"; radius: number }
| { kind: "square"; size: number };
function area(s: Shape) {
if (s.kind === "circle") {
return Math.PI * s.radius ** 2; // Circle に絞られる
}
return s.size * s.size;
}判別可能ユニオン(discriminated union)にしておくと switch や if で型が確定する。
詳しい書き方は 型の絞り込み にまとめてある。
3. 型定義を更新する・足す
npm install --save-dev @types/lodash自前で書くなら、types/old-lib.d.ts に使う関数を宣言し、tsconfig.json の include に含める。
declare module "old-lib" {
export function legacyFn(input: string): number;
}4. global を拡張する
// src/types/global.d.ts
export {};
declare global {
interface Window {
MY_APP: { version: string };
}
}宣言マージ公式(新しいタブで開く) のとおり、interface は同名で複数回書くと自動でマージされる。tsconfig.json の include に src/types/**/* が含まれているかも確認する。
よくある原因
- 型を明示していない。
const user = { id: "1", name: "a" }のように初期値から推論された型には、書いていないプロパティが含まれない。await res.json()の戻り値はanyなので、こちらはこのエラーにならない。 - ユニオン型のまま参照している。
type Shape = Circle | Squareでshape.radiusを読むと、Squareに無いため拒否される(Narrowing 公式(新しいタブで開く))。 - 型定義が足りない。
@typesや自前の.d.tsが古く、使うプロパティが宣言されていない。.d.tsがまったく無いパッケージは暗黙のanyになり、strictならこのエラーではなく TS7016 が出る。 - グローバルの拡張が足りない。
window.MY_APP = ...のようにグローバル変数を追加したが、declare globalで型を足していない。