見出し画像

[AI基礎解説]よく出るエラー辞典” Docker / WSL / Compose 編 — 症状→原因→対処（保存版）

GeneLab

ねらい：環境依存の地雷を“最短”で切り分け、再現→修正→再発防止まで型で回す。
対象：AI/WEBアプリ開発者（Mac / Windows + WSL2 / Linux）。
ゴール：症状 → 原因 → 対処をテンプレ化し、チーム全員が同じ手順で直せるようにする。


TL;DR（まずはこの順番で診断）

  1. エンジンが動いているか

    • docker info / docker version

    • docker context ls（Docker Desktop / WSL / remote の切替ミスが多い）

  2. 単体コンテナで再現するか

    • docker run --rm -it alpine:3 sh（最小でネット/権限を確認）

  3. ポート／ネットワーク

    • lsof -i :<PORT>（Mac/WSL） / netstat -ano | findstr :<PORT>（Win）

    • 社内プロキシ／DNS／ファイアウォール

  4. アーキとOS（ARM/AMD64）

    • exec format error / platform ミスマッチに注意

  5. ボリューム／権限

    • UID/GID 食い違い、WSLの metadata 設定

  6. Composeの記述と起動順

    • docker compose config で最終マージを確認

    • depends_on は起動順のみ（準備完了は見ない）。healthcheckで待つ

1. Docker デーモン／権限／接続

  • Cannot connect to the Docker daemon

    • 原因：エンジン停止、ソケット権限、コンテキスト違い

    • 対処：

      • Docker Desktopを起動（Mac/Win）

      • Linux：sudo systemctl status docker → sudo systemctl start docker

      • 権限：sudo usermod -aG docker $USER（再ログイン）

      • docker context ls で目的のエンジンに切り替え

  • permission denied while trying to connect to the Docker daemon socket

    • 原因：/var/run/docker.sock の権限

    • 対処：上記の docker グループ設定＋再ログイン／再起動

  • no space left on device（容量不足）

    • 対処：

      • docker system df（使用量の内訳）

      • docker system prune -af --volumes（思い切って掃除／要注意）

      • 画像・ボリュームの棚卸しを定期運用に

2. ビルド／実行のアーキテクチャ問題（ARM/AMD64）

  • exec format error / image operating system ‘linux/amd64’ cannot be used on this platform

    • 原因：MシリーズMac=ARM64、WSL/多くのCI=AMD64。ミスマッチで起動不能

    • 対処：

      • その場しのぎ：docker run --platform linux/amd64 <image>

      • Compose：

        1. services: app: image: your/app:latest platform: linux/amd64

      • 正攻法：マルチアーキでビルド（CIで --platform linux/amd64,linux/arm64）

  • QEMUエミュで極端に遅い

    • 対処：開発はネイティブアーキ用のイメージを使う、重いワークロードは同アーキのVM/マシンへ。

3. ポート競合／ネットワーク

  • OSError: Address already in use / EADDRINUSE

    • 原因：既に他プロセスが使用

    • 対処：

      • Mac/WSL：lsof -i :8000 → kill <PID>

      • Windows：netstat -ano | findstr :8000 → タスクマネージャで終了

      • .env でポートを可変に

  • 社内プロキシ／DNSでPull失敗／pip失敗

    • 対処：

      • docker build --build-arg HTTP_PROXY=... --build-arg HTTPS_PROXY=...

      • Composeの build.args / environment で明示

      • DNS：/etc/resolv.conf を確認（WSLは後述）

  • pull access denied, repository does not exist or may require 'docker login'

    • 原因：プライベートレジストリ／タグ名ミス

    • 対処：docker login <registry>、タグを再確認

4. ボリューム／権限／改行（CRLF）

  • PermissionError / EACCES（ボリューム内）

    • 原因：ホストとコンテナのUID/GID差

    • 対処：

      • コンテナ側ユーザをホストと合わせる、または chown -R

      • 開発用は :delegated ではなく標準マウントで挙動確認（Mac）

      • WSLは metadata オプション（後述）

  • .sh が ^M で動かない（/usr/bin/env: 'bash\r'）

    • 原因：CRLF 改行

    • 対処：

      • Git：git config --global core.autocrlf input（Mac/WSL）

      • .gitattributes を用意

        1. *.sh text eol=lf Dockerfile text eol=lf *.py text eol=lf

      • 既存ファイルは dos2unix で変換

5. WSL2 特有の落とし穴（Windows）

  • WSLの状態を確認

    • wsl -l -v（ディストリとバージョン）

    • wsl --status / wsl --update / wsl --shutdown

  • プロジェクトは Linux 側に置く

    • 原因：/mnt/c/... はI/O遅い

    • 対処：\\wsl$\Ubuntu\home\<you>\project 配下に置く（体感で数倍速）

  • 権限・パーミッションが崩れる

    • /etc/wsl.conf（ディストロ側）

      1. [automount] options = "metadata,umask=22,fmask=11"

    • 反映：wsl --shutdown → 再起動

  • DNS 解決が不安定

    • cat /etc/resolv.conf を確認

    • 必要なら自動生成を無効にして手動指定（※要ネットワーク規約に沿う）

  • 時計ズレでTLS/apt失敗

    • Windows側で時刻同期 → w32tm /resync、WSL再起動

  • Docker DesktopとWSLの整合

    • Docker Desktop設定で “Use the WSL 2 based engine” を有効化

    • 開発用ディストロにチェック（Resources → WSL Integration）

  • .wslconfig（リソース制御、Win側ユーザディレクトリ）

    1. [wsl2] memory=8GB processors=8 swap=4GB localhostForwarding=true

6. Dockerfile／ビルド文脈（context）の罠

  • 巨大contextでビルドが終わらない

    • 対処：.dockerignore を用意

      1. .git __pycache__/ node_modules/ *.log .venv/

  • COPYの相対パス／WORKDIRミス

    • 対処：WORKDIR /app → COPY . . の順番を固定し、意図通りか docker build ログで確認

  • キャッシュ無効化が必要

    • docker build --no-cache / docker compose build --no-cache

    • ベースイメージ更新は --pull を併用

7. Compose 特有の落とし穴（起動順・.env・override）

  • depends_on は“起動順”のみ（Ready ではない）

    • 対処：healthcheck を付け、service_healthy で待つ

  • .env の場所／変数補間の勘違い

    • .env は composeファイルと同じディレクトリが原則

    • 反映確認：docker compose config（最終的に展開された定義を出力）

  • 匿名ボリュームでホストの変更が反映されない

    • 対処：volumes: に明示のバインド（./src:/app/src）を使い、匿名ボリュームを消すなら docker compose down -v

  • ファイル分割・上書きの迷子

    • 対処：docker compose -f compose.yml -f compose.prod.yml config で最終形を確認

  • YAMLのタブ混入（パース失敗）

    • 対処：スペースのみ。エディタ設定でTab→スペース強制

  • 再起動戦略がなく落ちたまま

    • 対処：開発でも restart: unless-stopped を検討。原因調査は docker compose logs -f <svc>

8. トラブル切り分けテンプレ（コピペOK）

基本確認

docker info
docker version
docker context ls
docker system df

最小再現

docker run --rm -it alpine:3 sh
apk add --no-cache curl
curl -I https://example.com

ポート競合

# macOS/WSL
lsof -i :8000
# Windows（PowerShell）
netstat -ano | findstr :8000

Composeの実体を確認

docker compose config
docker compose ps
docker compose logs -f

クリーン再起動

docker compose down -v
docker compose up --build

9. 再発防止（チーム運用の型）

  • 週1のお掃除（画像・ボリュームの棚卸し）

  • .dockerignore と .env.example を必ず配布

  • healthcheck を標準装備（DB/ブローカー系は特に）

  • YAMLレビュー（Tab禁止、変数名の一貫性）

  • WSLポリシー（プロジェクトはLinux側／metadata／LF固定）をドキュメント化

まとめ

  • まずは エンジン→単体コンテナ→ポート/ネット→アーキ→権限→Compose の順で切り分け。

  • docker compose config と healthcheck が“分からない動き”を減らす鍵。

  • WSLは置き場所とmetadata、CRLF/LFに気をつけるだけでトラブルの半分が消える。

次のおすすめ


#Docker #WSL2 #DockerCompose #トラブルシューティング #開発環境構築 #AI開発 #DevOps

いいなと思ったら応援しよう！