うまくいかないとき集

コマンドの打ち間違い以外の詰まり——Desktop が動かない、pull が切れる、権限、キャッシュ、ポート衝突、Compose の version 警告、Windows の改行——を 症状 → 原因 → 対処 で並べたハブです。

参考（Docker 公式）

• Docker Desktop troubleshooting
• Docker Desktop WSL 2 backend on Windows
• File sharing（Windows settings）
• Version and name top-level elements（Compose）
• docker container run — Publish ports / Restart policies

目次

1. Docker Desktop が起動していない・応答しない
2. WSL2 関連の軽い詰まり
3. イメージの pull がタイムアウト・失敗する
4. permission denied（権限エラー）
5. ビルドキャッシュの噛み合わせが変
6. ポートが衝突する
7. Compose ファイルの version 警告
8. Windows の改行コード（CRLF）でスクリプトが壊れる
9. 症状別クイックリファレンス

Docker Desktop が起動していない・応答しない

症状

error during connect: this error may indicate that the docker daemon is not runningopen //./pipe/dockerDesktopLinuxEngine: The system cannot find the file specified.

docker ps や docker version を打つだけでこのエラーが出る場合、CLI 自体は問題なく、接続先の Docker Desktop（エンジン）が起動していない ことがほとんどです。

原因

対処

1. タスクトレイの Docker アイコンを確認し、なければ Docker Desktop を起動する
2. アイコンが「Starting...」の間は待つ（docker version が通るまで）
3. 直らない場合は Docker Desktop を完全終了 → 再起動
4. それでも直らない場合は Windows 自体を再起動（WSL2 / Hyper-V 周りの再初期化になる）

docker versiondocker info

docker info がサーバー側（Server: セクション）まで表示されれば、エンジンとの接続は回復しています。

WSL2 関連の軽い詰まり

Windows 版 Docker Desktop は既定で WSL 2 バックエンド を使います。ここでの軽い詰まりは、多くが「どの WSL ディストリビューションと連携しているか」の設定ズレです。

深い WSL2 の設定（メモリ上限・CPU 割り当てなど）は .wslconfig で調整できますが、学習用途で詰まった場合はまず Docker Desktop を再起動する だけで解消するケースが大半です。

イメージの pull がタイムアウト・失敗する

症状

Error response from daemon: Get "https://registry-1.docker.io/v2/": net/http: TLS handshake timeout

Error response from daemon: toomanyrequests: You have reached your pull rate limit

原因

対処

# 単純な再試行（一時的な障害はこれで直ることが多い）docker pull nginx:alpine# 認証してレート制限を緩和（Docker Hub アカウントがある場合）docker login

プロキシ環境では、Docker Desktop の Settings > Resources > Proxies にプロキシ URL を設定します。設定後は必ず Docker Desktop を再起動して反映させます。

permission denied（権限エラー）

症状

touch: /app/data/output.txt: Permission denied

EACCES: permission denied, open '/app/node_modules/.cache/...'

原因

Linux コンテナ内のプロセスは UID/GID で動作します。ベースイメージによっては非 root ユーザー（例: node イメージの node ユーザー）で実行され、ホストからバインドマウントしたディレクトリの所有者と食い違うと書き込みに失敗します。

対処

# 一時的にコンテナ側を root で実行して確認する（本番運用では非推奨）docker exec -u root -it <コンテナ名> sh

学習・検証用途であれば、Dockerfile 側で明示的に権限を揃える方法が分かりやすいです。

FROM node:22-alpineWORKDIR /appCOPY --chown=node:node . .USER node

--chown はコピー時点で所有者を指定できるため、あとから chmod / chown を打つより事故が起きにくいです。

ビルドキャッシュの噛み合わせが変

症状

• Dockerfile を書き換えたのに docker build の結果が変わらない
• RUN apt-get update の結果が古いパッケージ一覧のまま

原因

Docker のビルドは レイヤーごとにキャッシュ され、直前の命令までの内容が変わっていないレイヤーはキャッシュから再利用されます。apt-get update のような「外部の状態を取りに行く」命令は、Dockerfile の記述自体が変わらない限り再実行されない ため、パッケージ一覧が古いままキャッシュされることがあります。

# キャッシュを使わずに完全ビルド（case01 の親ディレクトリで実行）docker build --no-cache -t case01-ubuntu .\case01

case01 の Dockerfile が apt-get update && apt-get install ... && rm -rf /var/lib/apt/lists/* を 1 つの RUN にまとめているのは、update と install を別レイヤーに分けると update だけキャッシュされて install 対象が古くなる事故を避けるためです。

ポートが衝突する

症状

Error response from daemon: driver failed programming external connectivityon endpoint ...: Bind for 0.0.0.0:8080 failed: port is already allocated

原因

同じホストポートを複数の -p / ports 設定で公開しようとしている、または Windows 側の別プロセス（IIS Express、他の開発サーバーなど）がそのポートを使用中です。

対処

# どのコンテナがそのポートを使っているかdocker ps --filter "publish=8080"# Windows 側で誰がポートを使っているか（PowerShell）Get-NetTCPConnection -LocalPort 8080 -ErrorAction SilentlyContinue# 空いているポートに変更して起動docker run -d --name web-demo2 -p 8081:80 nginx

Compose の場合は compose.yaml の ports を書き換えるだけで済みます。

services:  web:    image: nginx:alpine    ports:      - "8081:80"   # 8080 が衝突する場合はここを変更

Compose ファイルの version 警告

症状

WARN[0000] the attribute `version` is obsolete, it will be ignored,please remove it to avoid potential confusion

原因

docker-compose.yml の先頭に version: "3.8" のような記述を残していると出る警告です。現在の Compose（Compose Specification）は version キーを見ずに常に最新の仕様として解釈 するため、このキーは後方互換のためだけに存在する obsolete な項目です。

対処

version: の行を削除するだけで警告は消え、動作にも影響しません。

# 変更前version: "3.8"services:  ubuntu:    build: .# 変更後（Compose Specification 準拠）services:  ubuntu:    build: .

新しく compose.yaml を書くときは、最初から version: を書かない書き方に統一しておくのがシンプルです。プロジェクト名を明示したい場合は代わりに name: トップレベル要素を使います。

name: my-projectservices:  ubuntu:    build: .

Windows の改行コード（CRLF）でスクリプトが壊れる

症状

Windows で作成した entrypoint.sh などのシェルスクリプトを Linux コンテナにコピーして実行すると、次のようなエラーになります。

exec /app/entrypoint.sh: no such file or directory

/bin/sh: 1: /app/entrypoint.sh: not found

ファイルは存在するのに「無い」と言われるのが典型的な症状です。

原因

Windows のエディタや Git の設定によっては、テキストファイルの改行が CRLF（\r\n） で保存されます。Linux のシェルは \r を含む先頭行（シバン行 #!/bin/sh\r）を正しく解釈できず、実行可能ファイルとして認識できません。

対処

# .gitattributes の例*.sh text eol=lf

# Dockerfile 内で変換する例（dos2unix が使えない最小イメージ向け）COPY entrypoint.sh /app/entrypoint.shRUN sed -i 's/\r$//' /app/entrypoint.sh && chmod +x /app/entrypoint.sh

この教材の case01 / case02 の Dockerfile はシェルスクリプトを持たず CMD に配列形式（["sleep", "infinity"]）を使っているため、この問題自体は発生しません。独自にシェルスクリプトを追加する場合にだけ注意が必要です。

症状別クイックリファレンス

Docker のトラブルは「エンジン自体の問題」「ネットワークの問題」「ファイル/権限の問題」「キャッシュの問題」「設定記法の問題」の 5 系統に大別できます。エラーメッセージの中の固有名詞（daemon、permission、cache、port、version など）に着目すると、どの系統かの見当が早くつきます。