Npm

冒頭まとめ npm installなどで次のエラーが出る場合、npmがHTTPS通信で検証した証明書の有効期限が切れています。 npm error code CERT_HAS_EXPIRED npm error errno CERT_HAS_EXPIRED 最初に接続先URLとnpmレジストリを確認してください。公式レジストリではなく、社内レジストリ、ミラー、プロキシを経由している場合は、その途中で提示された証明書が原因になることもあります。 次にnpmのcaとcafile、Node.jsのバージョンを確認します。古いCA証明書が明示的に設定されている場合は設定を更新し、Node.jsが古い場合はサポート中の版へ更新します。証明書の検証を無効にするstrict-ssl=falseは、安全な解決方法ではありません。 CERT_HAS_EXPIREDの意味 CERT_HAS_EXPIREDは、Node.jsのTLS処理が返すX.509証明書エラーです。Node.js公式文書では「証明書の有効期限が切れている」状態として定義されています。 npmはパッケージやメタデータをHTTPSで取得するとき、接続先から提示された証明書をNode.jsで検証します。証明書チェーンの検証対象に期限切れの証明書が含まれていると、npmは通信を中止し、このコードを表示します。 エラーはパッケージの依存関係やpackage-lock.jsonの内容そのものを示すものではありません。DNS解決とTCP接続の後に行われるTLS証明書の検証で失敗しています。Node.js公式のTLSエラーコード一覧で定義を確認できます。 最初に接続先と設定を確認する エラーの前後に表示されたURLを確認します。npmが使用する既定レジストリも調べてください。 npm config get registry https://registry.npmjs.org/以外が表示された場合は、社内レジストリやミラーの証明書を確認します。ただし、レジストリが公式URLでも、HTTPSプロキシが通信を中継していれば、実際に検証している証明書はプロキシが発行したものかもしれません。 続いて、Node.jsのバージョンとnpmの証明書設定を確認します。 node -v npm config get ca npm config get cafile npm config get strict-ssl caまたはcafileに値がある場合は、その設定が意図したものか、参照先の証明書が現在も有効かを確認します。strict-sslの既定値はtrueです。 環境変数も確認します。macOSやLinuxでは次を実行します。 printf '%s\n' "$NODE_EXTRA_CA_CERTS" PowerShellでは次のように確認できます。 $env:NODE_EXTRA_CA_CERTS 接続先やプロキシの証明書が期限切れの場合 社内レジストリ、キャッシュ用ミラー、HTTPSプロキシなどの証明書が期限切れなら、サーバーまたはプロキシ側で証明書を更新する必要があります。利用者側でnpmの検証を無効にしても、期限切れそのものは解消しません。 OpenSSLを利用できる環境では、実際の接続先ホストを指定して証明書の有効期間を確認できます。 openssl s_client -connect example.com:443 -servername example.com < /dev/null 2>/dev/null \ | openssl x509 -noout -subject -issuer -dates notAfterが有効期限です。ただし、プロキシを経由する環境でこのコマンドがnpmと同じ通信経路を通るとは限りません。ブラウザ、プロキシ管理画面、組織の証明書管理手段も併用し、npmが実際に受け取った証明書を確認してください。 公開レジストリ側の障害が疑われる場合は、npmのサービス稼働状況も確認します。社内レジストリやプロキシの場合は、管理者へ接続先URL、発生時刻、証明書の発行者と有効期限を伝えると調査しやすくなります。 npmのcaまたはcafileが古い場合 npmのcaは、レジストリとのSSL接続で信頼するCA証明書を直接指定する設定です。cafileは、1つ以上のCA証明書を含むファイルのパスを指定します。どちらも既定値はnullです。npm公式のconfig文書に仕様があります。 過去に社内CAや古い証明書を登録し、その設定だけが残っていると、現在の正しい証明書チェーンを検証できないことがあります。設定が不要になったことを確認できた場合は削除します。 npm config delete ca npm config delete cafile 削除後に値を確認し、もう一度インストールします。 ...

結論 gyp ERR! build error の build は、原因の名前ではありません。失敗したコマンドの名前です。node-gyp の実装は、処理が例外で終わったときに「そのコマンド名」と error をつないだ見出しを出します。だから configure error や install error も同じ書式で現れます。build と出ていれば、設定の段階は通っていて、組み立ての段階で落ちたという意味になります。 もう1つ押さえる点があります。この段階で node-gyp 自身が投げるエラーは、ほぼ1種類しかありません。実装では、呼び出した make か msbuild が 0 以外で終わったときに、終了コードをそのまま載せたエラーを作ります。つまり gyp ERR! stack の行は「外部のプロセスが失敗した」としか言っていません。 本当の原因は、その上にあります。組み立ての出力は node-gyp を素通りして画面に出るため、gyp ERR! の並びより前に、実際の失敗が文字として残っています。読む場所はそこです。 最初に確認すること gyp ERR! stack の1行目を見ます。 gyp ERR! build error gyp ERR! stack Error: `make` failed with exit code: 2 この形であれば、組み立てそのものが失敗しています。画面をさかのぼり、error: で始まる最初の行を探してください。複数並んでいても、最初の1件が起点です。 一方、1行目が次のような文であれば、失敗したのは組み立てではなく準備です。 gyp ERR! stack Error: Could not find *.sln file or Makefile. Did you run "configure"? gyp ERR! の末尾に並ぶ System、command、cwd、node -v、node-gyp -v の5行は、失敗のたびに必ず出る環境の記録です。原因は入っていません。ただし node -v の値は、次の原因1の判断に使います。 ...

結論 npm error code EAI_AGAIN は、名前を引く処理が一時的に失敗したという意味です。syscall の行には getaddrinfo が入ります。宛先のサーバーへ接続する前の段階で止まっており、レジストリの応答内容は関係ありません。 注意すべき点があります。npm はこのコードに専用の説明を持っていません。実装のコードごとの分岐には ENOTFOUND や EAI_FAIL はありますが、EAI_AGAIN は含まれておらず既定の扱いになります。したがって、ECONNRESET のときに出る「中継設定を確認してください」という案内も表示されません。表示されるのは、失敗した要求の内容を示す1文だけです。 切り分けの材料はエラー文の末尾にあります。getaddrinfo EAI_AGAIN の後ろに、引こうとした名前が入ります。ここがレジストリの名前なのか、中継先の名前なのかで、疑う場所が変わります。 最初に確認すること まず、失敗している名前を特定します。 npm install 2>&1 | grep -o "EAI_AGAIN [^ ]*" 次に、レジストリへ届くかを npm 自身の手段で確かめます。 npm ping このコマンドは現在の向き先へ疎通を試み、往復にかかった時間を表示します。ここで同じコードが返れば、原因は取得処理ではなく経路にあります。成功したり失敗したりする場合は、一時的な不調です。 名前を引く側の設定も確認してください。 cat /etc/resolv.conf npm config get registry npm config get proxy 原因別の確認方法と解決策 原因1：コンテナから名前を引く先へ届いていない コンテナの中でのみ失敗する場合です。実行環境が参照している宛先が、そのコンテナからは到達できません。 確認方法は、コンテナの内側から見ることです。 docker compose exec app sh -c 'cat /etc/resolv.conf' 記載されている宛先が、コンテナの外側でしか使えないものになっていることがあります。その場合、外側では成功して内側でだけ失敗します。 対処は、届く宛先を指定し直すことです。 services: app: dns: - 1.1.1.1 組織のネットワークでは、内部の宛先を指定する必要がある場合があります。管理者の指定に従ってください。 原因2：中継先を経由せず自分で名前を引いている 社内の回線で、中継の設定は入っているのに失敗する場合です。エラー文の末尾に出ている名前が、中継先ではなく接続先になっていれば、中継を経由していません。 確認方法は設定値と失敗名の突き合わせです。 npm config get proxy npm config get https-proxy npm config get noproxy 除外の一覧に接続先が含まれていると、その宛先だけ中継を通しません。結果として自分で名前を引こうとして失敗します。 ...

結論 npm error code ECONNRESET は、接続が相手側から切られたという意味です。npm はこのコードを他のネットワーク系と同じ分岐で扱うため、固有の説明は出ません。表示されるのは「ネットワーク接続に関する問題である」「多くの場合は中継の設定かネットワーク設定に問題がある」という2文と、中継設定の確認を促す1文だけです。 つまり文言からは原因を絞れません。切り分けの材料は3つあります。どの回線で起きるか、失敗する対象が毎回同じか変わるか、そして失敗するまでの時間です。 npm は取得に失敗した場合、既定で2回まで再試行します。待ち時間は10秒から始まり、上限は1分です。これを踏まえると、実行してすぐ落ちる場合と、数十秒かけて落ちる場合では見るべき場所が違います。 最初に確認すること まず、経路の設定を並べて確認します。 npm config get proxy npm config get https-proxy npm config get registry npm config get maxsockets proxy と https-proxy が null なのに社内の回線から実行している場合、原因1に当たります。環境変数側だけに設定されていることもあるため、そちらも見てください。 printenv | grep -i proxy 次に、失敗する対象が毎回同じかを確かめます。 npm install --loglevel verbose 2>&1 | tail -40 対象が実行ごとに変わるなら、特定のパッケージではなく接続の総量が問題です。同じ対象で止まるなら、その向き先が届いていません。 原因別の確認方法と解決策 原因1：中継の設定が npm に渡っていない 社内の回線からのみ失敗する場合です。npm の説明文も、まずこの可能性を挙げます。 確認方法は設定値の突き合わせです。公式の説明によれば、HTTP_PROXY や http_proxy の環境変数が設定されていれば、その内容が利用されます。npm 側の設定と環境変数のどちらか一方だけに値が入っていると、経路が定まりません。 対処は、組織から指定されている中継先へ揃えることです。 npm config set proxy http://proxy.example.com:8080 npm config set https-proxy http://proxy.example.com:8080 中継先を通さない宛先がある場合は、除外する一覧も設定してください。 ...

結論 npm error code ENOENT は、何かが見つからなかったという意味です。npm が加える説明も2文しかありません。「npm がファイルを見つけられないことに関係している」と述べ、file の値がある場合だけ「そのファイルが存在するか確認してください」と続きます。 したがって、原因を絞る材料は説明文ではなく、npm が併記する診断用の項目にあります。実装では code、syscall、file、path、dest、errno の6つのうち、値が入っているものだけを並べて出力します。このうち syscall が何をしようとして失敗したか、path がどこで失敗したかを示します。 読み方は単純です。syscall が open で path が package.json で終わっていれば、そのディレクトリにプロジェクトの定義が無いという意味になります。syscall が spawn git であれば、ファイルではなく外部コマンドが見つかっていません。path が node_modules の下を指していれば、導入済みのはずの中身が欠けています。 この2項目を見ないまま npm install を繰り返しても状況は変わりません。まず対象を特定してください。 エラーが発生する処理段階 npm の処理は段階に分かれており、ENOENT はどの段階でも起こります。ただし失敗した対象を見れば段階は特定できます。 第一段階はプロジェクトの読み取りです。npm はカレントディレクトリから package.json を探します。ここで見つからなければ、依存の解決にも取得にも進みません。 第二段階は依存の解決です。レジストリからの取得だけであれば外部コマンドは不要ですが、git の場所を指定した依存が含まれる場合、npm は git を起動します。この起動に失敗すると syscall が spawn git になります。 第三段階は取得と展開で、node_modules の下に書き込みます。前回の実行が途中で終わっていると、この段階の読み取りで欠けた対象に当たります。 第四段階は導入後のスクリプト実行です。ここで外部コマンドが見つからない場合も、同じ形の失敗になります。 段階が違えば path の指す場所も変わります。逆に言えば、path を見れば段階が分かります。 最初に確認すること まず、出力の診断用の行だけを抜き出します。 npm install 2>&1 | grep -E "npm error (code|syscall|path|file|dest|errno)" 出力はこの形になります。 ...

結論 npm error code ENOTEMPTY は、移動しようとした先が空でないディレクトリだったという意味です。npm はこのコードに専用の説明を持っておらず、既定の扱いになるため、画面に出るのは OS が返した1文だけです。 ここで押さえるべき点があります。npm は導入の過程で、置き換える対象を一度別名へ退避します。この移動が ENOTEMPTY で失敗した場合、実装は例外を握りつぶし、退避先を中身ごと削除してから移動をやり直します。つまり、単に古い退避先が残っていただけなら表には出ません。 したがって画面に出た時点で、それは2回目の失敗です。退避先を削除できなかったか、削除した直後に誰かが作り直したかのどちらかに絞れます。前者はファイルシステムの制約、後者は同時に動いている別のプロセスです。 読む場所は path と dest の2行です。path が退避される元、dest が退避先で、後者はドットで始まる名前になります。この名前は元の経路から機械的に決まるため、実行のたびに変わりません。 エラーが発生する処理段階 ENOTEMPTY は取得の段階では出ません。依存の解決も取得も終わり、実際に node_modules を書き換える段階で起きます。 第一段階は差分の計算です。npm は今ある木と目標の木を比べ、変更するものと削除するものを列挙します。 第二段階が退避です。変更または削除の対象になった浅い階層のものを、別名へ移動します。ここが ENOTEMPTY の主な発生場所です。退避しておく理由は、途中で失敗したときに元へ戻せるようにするためです。 第三段階が展開で、新しい内容を書き込みます。第四段階で退避したものを片付けます。 失敗が第二段階で起きると、npm は元へ戻す処理を試みます。このとき戻す方向の移動でも同じコードが出ることがあります。path と dest の関係が逆になっていれば、戻す側で失敗しています。 最初に確認すること まず、診断用の行を抜き出します。 npm install 2>&1 | grep -E "npm error (code|syscall|path|dest|errno)" 出力はこの形になります。 npm error code ENOTEMPTY npm error syscall rename npm error path /app/node_modules/lodash npm error dest /app/node_modules/.lodash-Ab3dEf9x dest の名前に注目してください。ドットに続けて元の名前があり、その後ろに8文字の英数字が付きます。実装では、元の経路をもとに固定の手順で短い文字列を作り、.<元の名前>-<その文字列> という名前にします。経路が同じであれば同じ名前になるため、何度実行しても変わりません。 次に、その退避先が実際に残っているかを見ます。 ls -a node_modules | grep "^\." dest と同じ名前が出てくれば、前回の中断が残っています。出てこないのに失敗する場合は、削除した直後に作り直されています。 ...

結論 npm error code ETARGET は、要求した版が候補の中に無いという意味です。npm が加える説明は1文だけで、「多くの場合、あなたか依存のどれかが存在しない版を要求している」と述べます。 前提として、パッケージ名そのものは見つかっています。名前が見つからない場合は E404 になります。つまり ETARGET が出ている時点で、確認すべきは名前ではなく版です。 読む場所は notarget の1行目です。実装は要求した名前と範囲を組み立てて No matching version found for <名前>@<範囲>. という文を作ります。ここに出ている範囲が、自分が書いたものと一致するかをまず見てください。一致しなければ、要求しているのは自分ではなく依存のどれかです。 もう1つ、この1行目には条件が付くことがあります。時刻による絞り込みが有効な場合、範囲の後ろに with a date before <日時> が加わります。この語句が見えたら、原因は版の指定ではなく絞り込みの設定です。 エラーが発生する処理段階 npm は依存の木を組み立てる過程で、パッケージごとに候補の一覧を取得し、その中から要求に合う1つを選びます。ETARGET はこの選択の段階で出ます。 第一段階は名前の解決です。レジストリから、そのパッケージの全版の情報をまとめた文書を取得します。ここで見つからなければ E404 になります。 第二段階は候補の絞り込みです。時刻による制約が設定されていれば、その日時より後に公開された版を候補から外します。この段階で候補が1つも残らなければ、別のコードが返ります。 第三段階が選択です。残った候補から、要求された範囲やタグに合うものを探します。見つからなければ ETARGET になります。 第四段階は取得です。ここまで来ていれば版は決まっているため、ETARGET は出ません。 つまり ETARGET は、候補の一覧は手に入っているが、その中に該当が無いという状態を指します。ネットワークや認証の問題ではありません。 最初に確認すること まず、notarget の1行目を正確に読みます。 npm error code ETARGET npm error notarget No matching version found for react@^99.0.0. npm error notarget In most cases you or one of your dependencies are requesting npm error notarget a package version that doesn't exist. @ の後ろが、実際に要求されている範囲です。自分の設定ファイルに書いた内容と一致するかを確かめてください。 ...

結論 npm ERR! code EACCES は、OS が書き込みや読み取りを拒んだという意味です。npm 自身の判断ではなく、システムコールが返した値がそのままコードになっています。 重要なのは、npm がこのエラーに対して2種類の文面を用意している点です。実装では、失敗した経路または書き込み先がキャッシュの置き場から始まっていて、かつ Windows でない場合にだけ、キャッシュの所有者を直す案内を出します。それ以外は、OS に拒まれたという汎用の文面になります。 つまり文面を読めば、直す対象が二分できます。キャッシュの所有者の話なのか、書き込み先そのものの権限の話なのか、という分かれ方です。 sudo を付けて回避するのは勧められません。多くの場合、それが次回以降の失敗の原因を作ります。root で作られたファイルがキャッシュに残り、通常の利用者では触れなくなるためです。 エラーが発生する処理段階 npm の処理は大きく3段階に分かれます。どの段階で拒まれたかで、疑う場所が変わります。 第一段階はキャッシュへの読み書きです。取得したパッケージの内容はキャッシュの置き場に保存されます。既定の場所は、POSIX 系が ~/.npm、Windows が %LocalAppData%\npm-cache です。 第二段階は導入先への展開です。通常の導入なら作業ディレクトリの node_modules、全体向けの導入なら prefix の下です。公式の説明によれば、全体向けの導入ではパッケージが {prefix}/lib/node_modules に置かれ、実行ファイルが {prefix}/bin に、説明書が {prefix}/share/man にそれぞれ結び付けられます。 第三段階は導入後のスクリプト実行です。ここで失敗する場合、拒まれているのは npm ではなくスクリプトが触ろうとした場所です。 npm ERR! path と npm ERR! syscall の2行が、どの段階かを教えてくれます。 最初に確認すること まず、拒まれた経路と操作を出力から読み取ります。 npm ERR! code EACCES npm ERR! syscall mkdir npm ERR! path /usr/local/lib/node_modules/typescript npm ERR! errno -13 npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/typescript' path がどこを指しているかで、次に見る場所が決まります。キャッシュの置き場の下なら原因1、prefix の下なら原因2、作業ディレクトリの下なら原因3です。 ...

結論 ERESOLVE unable to resolve dependency tree は、npm が依存関係の木を組み立てられなかったという意味です。実装では、peer 依存の衝突を解決できなかった時点で unable to resolve dependency tree という文言のエラーが投げられます。 読むべき場所は3か所です。While resolving: は何を導入しようとしていたか、Found: は木に既にある物、Could not resolve dependency: は満たせなかった要求です。この3行を突き合わせれば、どのバージョンとどの要求がぶつかっているかがその場で分かります。 --force や --legacy-peer-deps を付ければ先へ進めますが、これは衝突を解決するのではなく、誤った可能性のある解決を受け入れるという操作です。出力の最後の行にもそう書かれています。まず衝突の中身を読んでください。 最初に確認すること 画面に出る説明は深さ4段までに省略されています。全文はキャッシュの置き場に eresolve-report.txt として書き出されており、こちらには省略のない説明と機械可読の内容が入っています。 cat "$(npm config get cache)/eresolve-report.txt" 深い階層で起きている衝突は、画面の出力だけでは追い切れません。相手が分からないときは、まずこのファイルを開いてください。 次に、npm 自身のバージョンを確認します。peer 依存を厳密に扱う挙動は npm 7 からで、6 以前とは結果が変わります。 npm --version 原因別の確認方法と解決策 原因1：直接指定した2つのパッケージが、同じ物に別の版を求めている 最も多い形です。Found: に出ている版と、Could not resolve dependency: の peer の範囲を見比べてください。両方とも from the root project と書かれていれば、自分の設定ファイルで指定した2つがぶつかっています。 対処は指定の見直しです。どちらかを、相手の peer の範囲に収まる版へ揃えます。 npm view some-lib@2.0.0 peerDependencies 原因2：上流のパッケージが古い範囲のまま更新されていない Could not resolve dependency: の peer が、自分では指定していないパッケージから出ている場合です。更新版が出ていれば、それで解消します。 ...