npm の ENOTEMPTY エラー:原因と解決策

結論 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 と同じ名前が出てくれば、前回の中断が残っています。出てこないのに失敗する場合は、削除した直後に作り直されています。 ...

2026年8月8日 · ErrorLog