できない.dev

TypeScript「Property does not exist on type」の原因と直し方

Property 'x' does not exist on type 'Y' は、型定義を広げるか型ガードで絞り込めば消える。
実装は知っているのに型が知らないプロパティにアクセスすると出る。

公開: 更新:

症状できない · exit 2
npx tsc
src/bad.ts(3,18): error TS2339: Property 'email' does not exist on type '{ id: string; name: string; }'.
解決後できた · exit 0
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: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. 型を明示する

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/**/* が含まれているかも確認する。

よくある原因

  1. 型を明示していない。
    const user = { id: "1", name: "a" } のように初期値から推論された型には、書いていないプロパティが含まれない。
    await res.json() の戻り値は any なので、こちらはこのエラーにならない。
  2. ユニオン型のまま参照している。
    type Shape = Circle | Square で shape.radius を読むと、Square に無いため拒否される(Narrowing 公式(新しいタブで開く))。
  3. 型定義が足りない。
    @types や自前の .d.ts が古く、使うプロパティが宣言されていない。
    .d.ts がまったく無いパッケージは暗黙の any になり、strict ならこのエラーではなく TS7016 が出る。
  4. グローバルの拡張が足りない。
    window.MY_APP = ... のようにグローバル変数を追加したが、declare global で型を足していない。