エラーメッセージの読み方事典

104件のエラーメッセージを、意味・原因・対処の順で解きました。

直す命令には代償があります。git reset --hard はコミットしていない作業を捨て、強制プッシュは他人のコミットを消し、docker system prune は名前のないボリュームを削除します。該当する箇所には、その代償を書いてあります。

Git29

git のエラーはほぼすべて「その状態でそれをやると何かが失われる」という拒否であり、fatal: は何も変えずに止まったという意味なので、一行目より下の hint: 行に本当の解決策が書かれていることが多いです。

npm20

npm では原因は最後の六行ではなく最初の code XXXX の一行に書かれており、失敗が自分のコードではなく依存関係の木やネイティブビルドから来ている場合は、node_modules を消して入れ直すだけで半分は解けます。

JavaScript15

ブラウザと node の誤りは、たいてい何が壊れたかだけを告げ、なぜその値がそうなったかは告げません — undefined を読んだ、関数ではなかった、JSON ではなかった。ですから直す場所は投げた行ではなくその値を作った上流であり、?. や既定値でその行だけ黙らせると、同じ問題がもっと遠くで、もっと分かりにくい形で戻ってきます。

Python18

Python のトレースバックは答えを二つに分けて置きます — 最後の一行が何が誤りかを、その上のフレームがどこで誤ったかを示すので、最後の行だけ読むと名前は分かって場所を落とします。とくに NoneType や KeyError のように値が無くて出る誤りは、落ちた場所より、その値を作った上のフレームに原因があります。

ModuleNotFoundError: No module named 'requests'sys.path にあるディレクトリを全部見たが、その名前のモジュールが無いという意味です。まだ入れていないか、入れた先が別のインタープリタであるかのどちらかで、仮想環境の外で pip install して中で実行すると必ずこうなります。python -m pip install と書けば今動かしているインタープリタに直接入るので、このずれは消えます。error: externally-managed-environmentこの Python は OS か Homebrew が管理しているもので、pip がそこへ書き込むのを拒んでいます（PEP 668）。システムのインタープリタに対して pip install したのが原因で、このメッセージは「仮想環境を作れ」という案内です。--break-system-packages は名前のとおりシステム側のパッケージを壊しうるので、.venv を作ってそこに入れるのが答えです。ImportError: cannot import name 'User' from partially initialized module 'models' (most likely due to a circular import)二つのモジュールが互いを import しているため、まだ半分しか読み込まれていないモジュールから名前を取り出そうとしています。A が B を、B が A を呼ぶ形で起こり、ファイルを分けた直後に型ヒントのために import を戻すときによく出ます。from y import Thing を import y に変え、関数の中で y.Thing と書けば参照が後ろにずれ、循環が問題になりません。IndentationError: unexpected indentその行が前の行より深く入っているのに、深くしてよい理由になるコロンが上にありません。貼り付けたコードが自前の字下げを連れてきたか、if の行を消して中身だけ字下げのまま残した場合が多いです。エラーが指す行の先頭の空白を取れば直り、見分けがつかないときは cat -A でその行を出すと空白とタブが見えます。TabError: inconsistent use of tabs and spaces in indentation一つのブロックの中でタブと空白が混ざっており、どの行が深いのかを Python が決められません。タブを入れる編集器から貼り付けたときや、二人が別々の設定で同じファイルを触ったときに起こり、画面上は全く同じに見えるので目では見つかりません。python -m tabnanny app.py がずれた行番号を出し、あとはそのファイルを編集器で空白四つに統一すれば終わりです。SyntaxError: invalid syntaxその位置で文として読み進められなかったという意味で、原因は指された行ではなく多くはその前の行にあります。閉じていない括弧や引用符、抜けたコロン、Python 2 の print "x" が主な原因で、括弧が開いたままだとパーサは何行も進んでから諦めます。python -m py_compile app.py なら実行せずに文法だけ確かめられ、3.10 以降は文言がずっと具体的になるので、Python を上げること自体が診断になります。TypeError: 'NoneType' object is not subscriptable[...] で取り出そうとしたその値が None だという意味です。上流の何かが黙って None を返しており、鍵の無い dict.get() や一致しなかった re.match、通った経路に return が無い関数が典型です。落ちた場所で None を弾くより、なぜ None なのかを上へ辿ってください — None を飛ばす if を一つ足しても、同じ誤りが次の行に移るだけです。AttributeError: 'NoneType' object has no attribute 'get'ドットの左のオブジェクトが None なので、求めた属性やメソッドが存在しません。前の nonetype-not-subscriptable と根は同じで、見つからなければ None を返す関数、たとえば BeautifulSoup の find() や re.search() の結果にそのまま続けて書いたときに特に出ます。まずその関数が何を探していたのかを出力し、見つからないのが正常な場合はその分岐を明示的に扱ってください。KeyError: 'name'その鍵が dict に無いという意味です。引用符の中がまさに探した鍵なので、まずそこを見てください — 打ち間違い、大文字小文字の違い、あるいは API 応答の形が思っていたものと違う場合です。無くてもよい値なら d.get("name") で None が返り、d.get("name", 0) で既定値を渡せますが、必ずあるべき値に .get を使うと、誤りの代わりに None がコードの奥へ流れ、ずっと遠くで壊れます。IndexError: list index out of rangeリストに無い位置を番号で呼びました。長さが n なら最後の番号は n-1 なので、range(len(x) + 1) や x[len(x)] は必ずここで止まり、空のリストに x[0] をするのも同じ誤りです — 前段の絞り込みや split が何も残さなかったときによく起きます。番号で回す代わりに for item in items: で回せばこの種の不具合は構造的に消え、位置が本当に必要なら enumerate(items) を使ってください。ValueError: invalid literal for int() with base 10: '3.5'int() に整数として読めない文字列を渡しました。引用符の中がその文字列です。'3.5' のような小数点、空文字列、改行の付いた入力、'1,000' のような桁区切りが主な原因です。小数点なら int(float(s)) の二段で通りますが、四捨五入ではなく小数部が切り捨てられます。人が打ち込む値なら、最初から try/except ValueError で包むほうが正直な対処です。UnicodeDecodeError: 'utf-8' codec can't decode byte 0xff in position 0: invalid start byteファイルやバイト列を UTF-8 として読もうとして、UTF-8 では許されないバイトに当たったという意味です。位置とバイト値が文言に書かれており、多くは Windows から来た cp1252 や euc-kr の CSV、そもそもテキストでない画像や zip、解凍し忘れた gzip です。本当のエンコーディングを調べて encoding= で渡すのが正解で、errors="replace" は読み終えられますがそのバイトが疑問符に変わり、データは静かに壊れたまま先へ進みます。ZeroDivisionError: division by zero0 で割ったという意味です。実際には定数の 0 ではなく、数えた件数が 0 だった場合がほとんどで、平均を出すコードで一覧が空だったり絞り込みが何も残さなかったときが典型です — 開発用のデータでは必ず通り、本番で初めて落ちる種類です。割る前に分母が 0 かを見て、0 のとき何を返すかを決めてください。0 を返す、None を返す、例外をそのまま上げるは別々の判断で、それぞれが正しい場面があります。RecursionError: maximum recursion depth exceeded関数が自分を呼ぶ深さが既定の上限 1000 を超えたという意味です。本当に深い計算よりも、止める条件が無いか届かない場合のほうがずっと多く、__getattr__ や property の中で自分の属性をまた読むような間接再帰もここに来ます。まずトレースバックで繰り返されている二、三のフレームを見つけて基底条件を直してください。sys.setrecursionlimit() で上限は上げられますが、本物の C スタックを踏み越えられるようになり、例外ではなく Python 自体が丸ごと落ちます — ループに書き換えるほうが安全です。UnboundLocalError: cannot access local variable 'count' where it is not associated with a value関数の本体のどこかでその名前に代入していると、Python はその名前を関数のローカル変数と決めます。つまり代入より前に読んだということです。外側の同名の値が見えると思っていた場合や、count += 1 のように読んで書く演算を初めて書いたときに出ます。関数の中で count = 0 から始めるのが普通の答えで、本当にモジュール側の値を変えたいなら global count と書けますが、その値を誰が書き換えるのか追いにくくなる代償が付きます。3.10 までは同じ誤りが 'local variable referenced before assignment' と出ていました。TypeError: greet() takes 1 positional argument but 2 were given受け取る約束より一つ多く渡したという意味で、数の差がちょうど一つなら、ほぼ必ず self です。クラスの中のメソッドを def greet(name): と定義すると、obj.greet("x") を呼んだ時点で Python が obj を最初の引数として渡すため、引数は二つになります。メソッドなら def greet(self, name): と self を受け取る形に直し、インスタンスが不要な関数なら @staticmethod を付けてください。PermissionError: [Errno 13] Permission deniedその経路に対するその操作を OS が拒みました。/var/log や /usr のように他人の所有する場所に書こうとした、コンテナで host のボリュームの UID がコンテナのユーザと違う、あるいは見落とされがちですが、ファイルではなくそれを収めるディレクトリに書き込み権限が無い — 新しいファイルを作るにはディレクトリの権限が要ります。まず ls -ld で所有者とモードを確かめ、sudo に頼る前に書ける場所へ経路を移すことを考えてください。sudo で作ったファイルは、次に sudo 無しで開くとまた同じ誤りを出します。OSError: [Errno 98] Address already in useそのポートを既に別のプロセスが握っているため bind に失敗したという意味です。前のサーバが完全に終わっていない、自動再読み込みが二つ立ち上げた、同じポートを Docker のコンテナが既に公開している、のいずれかです。lsof -i :8000 で握っている PID が分かるのでそれだけ片付ければよく、kill -9 で手当たり次第に消す前にプロセス名を確かめてください。errno は OS ごとに違い、Linux では 98、macOS では 48 と出ます。

ビルドと型10

ビルドの誤りは実行前に道具が拒んだものなので、その場で何かを壊すわけではありません。代わりに二つを問います — 型や経路を実際の形に合わせて直すのか、それとも as any や抑制のコメント一つでその行だけ通すのか。そして大文字小文字や拡張子、環境変数のように自分の環境でだけ正しいものは、ここで初めて姿を見せます。

error TS2307: Cannot find module 'lodash' or its corresponding type declarations.tsc がそのモジュール自体も、そのモジュールの型宣言も見つけられなかったという意味で、文言が両方を言っているのが肝心です — パッケージがそもそも無い場合も、入っているが型だけ無い場合もあります。入れてあるのにこう出るなら型のほうなので、npm i -D @types/lodash のように対になる型パッケージを入れます。ただし近年のパッケージは型を同梱しており @types が存在しないことも多いです。相対経路の import でこれが出たら、大文字小文字と tsconfig の paths を見てください — 自分のファイルを指す経路は @types と無関係です。error TS2339: Property 'user' does not exist on type 'Request'.その型にその属性が宣言されていないという意味です。ライブラリの型に無いフィールドを足そうとした場合（Express の Request に user を付けるのが代表例）、打ち間違い、あるいは絞り込まれていない union の片方にしか無い属性を読んだ場合に出ます。型を実際の形に合わせて直すのが答えで、union なら 'x' in y や判別用のフィールドで絞れば、その分岐の中では参照できます。as any で消すのはコンパイラの口を塞ぐだけなので、その場所は綴りを間違えた属性名まで通すようになります。error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.関数が受け取る型と渡した値の型が違うという意味で、文言が順に書いてくれます — 前が渡したもの、後ろが受け取るはずのものです。最も多いのは、フォームの入力値や URL のクエリ文字列、JSON から来た値が文字列のまま数値を受け取る場所に入る場合です。境界で一度変換するのが答えですが、Number(value) は失敗しても例外ではなく NaN を返すので、その NaN が流れていかないよう検査が必要です — Number.isFinite(n) がその場所です。error TS18048: 'user' is possibly 'undefined'.その値が undefined かもしれないのに、その可能性を扱っていないという意味で、これは tsc が先回りして捕まえた将来の Cannot read properties of undefined です。省略可能なフィールド、配列の find() の結果、設定されていないかもしれない環境変数にそのまま続けて書いたときに出ます。無いときにどうするかを決めるのが答えで、関数の頭で if (!user) return null と切るか、user?.name で短く抜けます。感嘆符を付けて user!.name と消すのは「私が保証する」という宣言で、その保証が誤っていれば実行時の例外として返ってきます — 検査と違い、安全網を何も残しません。error TS7006: Parameter 'req' implicitly has an 'any' type.引数に型が書かれておらず、tsc が推論する手がかりも無かったため暗黙に any になったという意味で、noImplicitAny が有効ならそれを誤りとみなします。JavaScript から移したファイルや、コールバックを別の変数に取り出したときに出ます。逆に items.map(x => ...) のように文脈のある場所では tsc が推論するので、これは出ません。そこに型を書くのが答えです。any と明示して通すこともできますが、それはその引数について検査を完全に切る選択です — 何か分からないときは unknown のほうが正直で、使う前に絞ることを強制します。Parsing error: Unexpected tokenESLint がそのファイルに規則を当てる前、文法を読む段階で止まったという意味です。本当にコードが壊れている場合より、パーサがその文法を知らない場合のほうがずっと多いです — TypeScript のファイルを既定のパーサで読んだ、JSX を有効にしていない、デコレータやごく新しい文法を古いパーサに渡した、などです。npx eslint --print-config app.ts をそのファイルに対して走らせると、実際に適用される parser と parserOptions がそのまま出るので、当てずっぽうより先にそれを見てください。TypeScript なら @typescript-eslint/parser が必要で、そのファイルをそもそも検査しないのなら ignores に入れるのが正解です。You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file.webpack が Module parse failed の後に付ける行で、そのファイルを JavaScript として読もうとしたが JavaScript ではなかったという意味です。TypeScript や JSX、CSS、画像、.vue のように変換が必要なファイルを module.rules に規則無しで import したか、node_modules のパッケージが未コンパイルのソースを配っていて、そのフォルダが exclude に入っている場合です。その拡張子に合う loader の規則を module.rules に足すのが答えで、どのファイルで止まったかは文言の上に出る経路が教えます。exclude: /node_modules/ を消して片付けるとビルド全体が目に見えて遅くなるので、そのパッケージ一つだけを例外にするほうが良い取引です。Failed to resolve import "./utils" from "src/main.ts". Does the file exist?その経路にファイルが見つからなかったという意味で、一緒に出る "Does the file exist?" が本当に確かめるべき三つを指しています — 名前の大文字小文字、拡張子、そして tsconfig や vite.config の別名です。macOS と Windows のファイルシステムは大文字小文字を区別しないので、./Utils と書いても自分の環境では動き、Linux で動く CI と配備で初めて壊れます — この誤りが「自分の環境では動く」の最も多い正体です。git ls-files src | grep -i utils でリポジトリに実際どの綴りで入っているかを確かめてください。別名（@/utils）なら vite.config の resolve.alias と tsconfig の paths の両方を合わせる必要があり、片方だけ直すと編集器は黙るのにビルドだけ壊れ続けます。You're importing a component that needs useState. This React hook only works in a client component.App Router では全てのコンポーネントが既定でサーバコンポーネントであり、useState のようにブラウザでしか意味を持たないフックを使うファイルを、サーバコンポーネントが import したという意味です。指示子はファイルの一番上の 'use client' 一行で、付けるとそのファイルとそれが import する全てがクライアントの束に入ります — だからページ全体ではなく、状態が必要な最小の断片にだけ付けるのが安い選択です。逆向きに、クライアントコンポーネントが子としてサーバコンポーネントを受け取る形に分ければ、データ取得はサーバに残せます。Next.js 13 では同じ状況が "It only works in a Client Component but none of its parents are marked with \"use client\"" と書かれていました。The engine "node" is incompatible with this module. Expected version ">=20"入れようとしているパッケージが package.json の engines に必要な node の版を書いており、今使っている版がその範囲の外だという意味です。後ろに付く Expected と Got が要求範囲と自分の版を並べて見せるので、その二行だけ見れば足ります — CI でだけ出るなら、そこの node の版が自分の環境と違うということです。nvm install 20 && nvm use 20 で node を上げるのが正面の答えで、.nvmrc や CI の設定にも同じ版を書いておけば次にまたずれません。yarn の --ignore-engines で押し通せますが、それは警告を消すだけで互換性を作らないので、そのパッケージが新しい構文を使えば実行中に構文誤りとして落ちます。npm は同じ状況を EBADENGINE の警告として知らせ、既定では設置を止めません。

Docker12

docker の誤りは、まずどの層で起きたかを分けないと読めません — クライアントがデーモンに届かない、レジストリが拒む、ビルド中に RUN が失敗する、コンテナが起動した途端に死ぬ、はそれぞれ別の問題です。とくにビルドと実行の層では文言そのものが理由ではなく、中で動いていた命令が残した出力に理由があり、直す命令の代償も層ごとに違います。

エラーメッセージの読み方

一行目から読みます。下に行くほど道具の内部の話で、原因はたいてい一番上に書かれています。
ファイル名と行番号があればそこが出発点です — スタックの最上段ではなく、自分が書いたファイルが出てくる一番上の行です。
文句はそのまま検索します。ただし自分のパスや変数名は消します — その部分が検索を邪魔します。
同じ事情が道具の版ごとに違う言い方で出ます。結果が合わないときは版番号も入れてみます。
直す命令を貼る前に、その命令が何を捨てるかを確かめます。取り消せないものが混ざっています。

よくある質問

Q. エラー文句を訳さないのはなぜですか。

検索するものだからです。道具は英語で出力し、訳した文句では何も見つかりません。言語に合わせるのは意味と対処だけです。

Q. 手元の画面と少し違います。

道具は版ごとに言い方を変えます。自分のパスや名前を消して残る骨格が同じなら同じエラーです。版が違うときは版番号も検索に入れます。

Q. 直す命令をそのまま実行してよいですか。

何を捨てるかを先に見ます。git reset --hard、強制プッシュ、docker system prune は戻せないものを消します — 該当する箇所には書いてあります。

Q. ここに無いエラーはどう探しますか。

文句から自分のパス・名前・数字を消し、残った部分だけを検索します。その残りが道具の作者が書いた文で、それで探すと結果が合います。