Docker クライアントとデーモンの API バージョン不一致対策

Contents

1 1. エラーメッセージと典型的な発生シーン
- 1.1 典型的なシチュエーション
2 2. Docker API のバージョニングと互換性ルール
- 2.1 2‑1. 下位互換（Backward Compatibility）
- 2.2 2‑2. 上位互換（Forward Compatibility）
3 3. 現在走っているバージョンを取得する方法
4 4. デーモン側の MinAPIVersion を確認する手順
- 4.1 4‑1. Linux/macOS (Unix ソケット)
- 4.2 4‑2. Windows (PowerShell)
5 5. 環境変数 DOCKER_API_VERSION の設定とスコープ
6 6. Docker Desktop / Docker Engine の再起動手順
7 7. CI/CD パイプラインでの自動対処例
8 8. トラブルシューティングチェックリスト
9 9. 記事まとめ（要点）

スポンサードリンク

1. エラーメッセージと典型的な発生シーン

エラーメッセージ	主な意味
`Error response from daemon: client version X.Y is too new. Maximum supported API version is Z.W`	クライアントが要求する API バージョン X.Y が、デーモン（サーバー）が対応できる最大バージョン Z.W を超えている
`Error response from daemon: client version X.Y is too old. Minimum supported API version is Z.W`	クライアントが古すぎて、デーモンが要求する最小 API バージョン Z.W 未満である

典型的なシチュエーション

シーン	原因例
Docker Desktop（または Engine）をアップデートした直後に、古い `docker` CLI が残っている	デーモン側が新バージョンに追随し、CLI が旧バージョンのまま
CI ランナーで固定された `docker` パッケージ（例: `docker.io=20.10.*`）を使用している	ホスト上の Engine と CLI のバージョン差が発生
テストフレームワークやプロキシツールが内部的に API バージョンをハードコードしている	TestContainers、Traefik などで `dockerApiVersion` が固定

参考: Docker の公式ドキュメント「Docker Engine API versioning」では、クライアントとサーバーのバージョンが食い違う場合に上記エラーが返される旨が明示されています。

2. Docker API のバージョニングと互換性ルール

Docker Engine の API は MAJOR.MINOR（例: 1.44）で管理され、次の二つの概念が重要です。

2‑1. 下位互換（Backward Compatibility）

デーモンは 最小サポート API バージョン (MinAPIVersion) を内部的に保持します。
クライアントが MinAPIVersion 以下を要求した場合、デーモンは自動的にそのバージョンで応答し、互換性が保たれます。

公式: 「Docker Engine は後方互換性を保証する」(https://docs.docker.com/engine/release-notes/#backward-compatibility)

2‑2. 上位互換（Forward Compatibility）

新機能やエンドポイントは 特定の API バージョン以上 が必要です。
クライアントが新バージョンを要求し、デーモン側がそのバージョンに未対応の場合は client version too new エラーになります。

例: BuildKit の拡張機能は API 1.42 以上でのみ利用可能です（https://docs.docker.com/engine/reference/builder/#buildkit）。

3. 現在走っているバージョンを取得する方法

3‑1. 基本コマンド

docker version --format 'Client={{.Client.APIVersion}} Server={{.Server.APIVersion}}'

1 2	docker version --format 'Client={{.Client.APIVersion}} Server={{.Server.APIVersion}}'

出力例 Client=1.44 Server=1.43
左側が CLI が認識している API バージョン、右側がデーモンがサポートするバージョンです。

3‑2. スクリプトで個別取得（CI 向け）

# クライアントだけ
client_api=$(docker version --format '{{.Client.APIVersion}}')

# サーバーだけ
server_api=$(docker version --format '{{.Server.APIVersion}}')

# クライアントだけ

client_api=$(docker version --format '{{.Client.APIVersion}}')

# サーバーだけ

server_api=$(docker version --format '{{.Server.APIVersion}}')

3‑3. 補足：Docker Engine のリリースノートでバージョン対応表を確認

公式: 「Engine API version history」
ここに、各 Docker Engine リリースがサポートする最小・最大 API バージョンが一覧化されています。

4. デーモン側の MinAPIVersion を確認する手順

docker info の標準出力には MinAPIVersion が表示されませんが、Engine の内部 /info エンドポイントから取得可能です。

4‑1. Linux/macOS (Unix ソケット)

curl --silent --unix-socket /var/run/docker.sock http://v1.24/info | jq -r '.MinAPIVersion'

1 2	curl --silent --unix-socket /var/run/docker.sock http://v1.24/info \| jq -r '.MinAPIVersion'

jq がインストールされていない場合は grep と sed でも取得可能です。

4‑2. Windows (PowerShell)

# Docker Desktop の場合、named pipe を使用
$uri = 'http://v1.24/info'
Invoke-RestMethod -Uri $uri -UseBasicParsing -Headers @{'Host'='docker'} `
    -WebRequestSession (New-Object Microsoft.PowerShell.Commands.WebRequestSession) `
    -OutFile $null -ErrorAction Stop | Select-Object -ExpandProperty MinAPIVersion

# Docker Desktop の場合、named pipe を使用

$uri = 'http://v1.24/info'

Invoke-RestMethod -Uri $uri -UseBasicParsing -Headers @{'Host'='docker'} `

-WebRequestSession (New-Object Microsoft.PowerShell.Commands.WebRequestSession) `

-OutFile $null -ErrorAction Stop | Select-Object -ExpandProperty MinAPIVersion

ポイント: v1.24 は API の最低バージョンで、実際に取得できるエンドポイントはデーモンがサポートしているものです。失敗した場合は、Docker Engine が古すぎて /info エンドポイント自体が存在しない可能性があります。

5. 環境変数 DOCKER_API_VERSION の設定とスコープ

環境変数を使うとクライアント側で API バージョン交渉を強制できます。以下は OS 別の設定例です。

OS	永続化（シェル）	永続化（システム全体）
Linux/macOS (Bash/Zsh)	`export DOCKER_API_VERSION=1.43` （`.bashrc`/`.zshrc` に追記）	`/etc/environment` に `DOCKER_API_VERSION=1.43` を追加し、再起動
Windows PowerShell	`$env:DOCKER_API_VERSION = "1.43"`（プロファイルに追記）	システム環境変数 → 「環境変数」画面で新規作成
Windows CMD	`set DOCKER_API_VERSION=1.43`（バッチファイルへ書く）	同上、レジストリ経由で永続化

設定は そのシェル／ジョブが開始された瞬間から有効 です。CI ランナーではスクリプト冒頭に export DOCKER_API_VERSION=...（Linux/macOS）や $env:DOCKER_API_VERSION="..."（PowerShell）を書くだけで済みます。

6. Docker Desktop / Docker Engine の再起動手順

API バージョン変更後は、デーモンが新しい設定を読み込むよう 再起動 が必要です。プラットフォーム別にまとめました。

プラットフォーム	手順
Linux (systemd)	`bash sudo systemctl restart docker` 再起動完了後 `docker version` で確認
macOS	1. メニューバーの Docker アイコン → Troubleshoot → Restart Docker Desktop 2. CLI だけで再起動したい場合は `osascript -e 'quit app "Docker"' && open /Applications/Docker.app`
Windows (PowerShell)	`powershell Restart-Service com.docker.service` GUI からは Settings → Troubleshoot → Restart Docker Desktop を選択
Docker Desktop（全 OS）	UI の Troubleshoot > Restart Docker Desktop は、内部の Engine と CLI 両方をリロードします。設定変更が反映されない場合はこの手順が必須です。

再起動後に docker version --format '{{.Client.APIVersion}}/{{.Server.APIVersion}}' を実行し、両者が一致していることを必ず確認してください。

7. CI/CD パイプラインでの自動対処例

以下は GitHub Actions（Ubuntu ランナー）と Azure Pipelines（Windows ランナー）のサンプルです。Docker Desktop の GUI 再起動ができない環境では、デーモンプロセスだけをリスタートします。

7‑1. GitHub Actions（Linux）

name: CI with Docker API version fix
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      # ① 環境変数で API バージョンを固定
      - name: Set Docker API version
        run: echo &quot;DOCKER_API_VERSION=1.43&quot; &gt;&gt; $GITHUB_ENV   # 永続化

      # ② 必要ならデーモン再起動（systemd が利用できる場合）
      - name: Restart Docker daemon
        if: runner.os == 'Linux'
        run: |
          sudo systemctl restart docker
          sleep 5   # 待機して安定化

      # ③ バージョン一致確認（失敗したらジョブ停止）
      - name: Verify API version match
        run: |
          client=$(docker version --format '{{.Client.APIVersion}}')
          server=$(docker version --format '{{.Server.APIVersion}}')
          echo &quot;client=$client server=$server&quot;
          [[ &quot;$client&quot; == &quot;$server&quot; ]] || exit 1

name: CI with Docker API version fix

on: [push, pull_request]

jobs:

build:

runs-on: ubuntu-latest

steps:

- name: Checkout repository

uses: actions/checkout@v4

# ① 環境変数で API バージョンを固定

- name: Set Docker API version

run: echo "DOCKER_API_VERSION=1.43" >> $GITHUB_ENV # 永続化

# ② 必要ならデーモン再起動（systemd が利用できる場合）

- name: Restart Docker daemon

if: runner.os == 'Linux'

run: |

sudo systemctl restart docker

sleep 5 # 待機して安定化

# ③ バージョン一致確認（失敗したらジョブ停止）

- name: Verify API version match

run: |

client=$(docker version --format '{{.Client.APIVersion}}')

server=$(docker version --format '{{.Server.APIVersion}}')

echo "client=$client server=$server"

[[ "$client" == "$server" ]] || exit 1

7‑2. Azure Pipelines（Windows）

trigger:
- main

pool:
  vmImage: 'windows-latest'

steps:
- powershell: |
    # ① 環境変数設定 (PowerShell スコープ)
    $env:DOCKER_API_VERSION = &quot;1.43&quot;
    # ② Docker デーモン再起動
    Restart-Service com.docker.service -Force
    Start-Sleep -Seconds 5
    # ③ バージョン確認
    $client = docker version --format '{{.Client.APIVersion}}'
    $server = docker version --format '{{.Server.APIVersion}}'
    Write-Host &quot;client=$client server=$server&quot;
    if ($client -ne $server) { exit 1 }
  displayName: 'Fix Docker API version on Windows'

trigger:

- main

pool:

vmImage: 'windows-latest'

steps:

- powershell: |

# ① 環境変数設定 (PowerShell スコープ)

$env:DOCKER_API_VERSION = "1.43"

# ② Docker デーモン再起動

Restart-Service com.docker.service -Force

Start-Sleep -Seconds 5

# ③ バージョン確認

$client = docker version --format '{{.Client.APIVersion}}'

$server = docker version --format '{{.Server.APIVersion}}'

Write-Host "client=$client server=$server"

if ($client -ne $server) { exit 1 }

displayName: 'Fix Docker API version on Windows'

7‑3. ツール側のロック解除例

ツール	バージョンロック解除方法
TestContainers (Java)	`testcontainers.properties` に `dockerApiVersion=1.43` を記載、または最新リリース (`2.3.x`) にアップデートすると自動適応
Traefik (Docker provider)	`traefik.yml` の `providers.docker.api.version: "1.43"` を追加。公式ドキュメント（https://doc.traefik.io/traefik/providers/docker/#api-version）を参照

8. トラブルシューティングチェックリスト

手順	実行コマンド / 操作	確認ポイント
1️⃣ バージョン取得	`docker version --format 'Client={{.Client.APIVersion}} Server={{.Server.APIVersion}}'`	クライアントとサーバーが同一か
2️⃣ MinAPIVersion 確認	(Linux) `curl --unix-socket /var/run/docker.sock http://v1.24/info \\| jq -r .MinAPIVersion` (Windows) PowerShell の `Invoke-RestMethod`	デーモンが許容する最小バージョン
3️⃣ 必要に応じて環境変数設定	`export DOCKER_API_VERSION=1.43`（Linux/macOS） `$env:DOCKER_API_VERSION="1.43"`（PowerShell）	設定がシェル／ジョブの先頭で行われているか
4️⃣ デーモン再起動	`sudo systemctl restart docker` / `Restart-Service com.docker.service` / UI の Restart Docker Desktop	再起動後に設定が反映されたか
5️⃣ 再確認	同じく `docker version --format ...`	クライアント＝サーバーで一致していること
6️⃣ ツール側のバージョンロックチェック	テストフレームワークやプロキシ設定ファイルを確認	必要に応じて `dockerApiVersion`/`api.version` を上書き

9. 記事まとめ（要点）

エラーは API バージョン不整合 が根本原因。まずは docker version と /info エンドポイントで実際の数値を取得。
Docker Engine は 下位互換 を保証し、最小サポートバージョン (MinAPIVersion) を持つ。上位機能はクライアント側が新しすぎてもエラーになる。
docker version --format によりスクリプトフレンドリーに クライアント/サーバー API を取得できるので、CI の前段で自動比較を組み込むと安全。
環境変数 DOCKER_API_VERSION を OS 毎に設定し、シェル／ジョブスコープで有効化すれば手軽にバージョン調整が可能。
設定変更後は必ず Docker デーモンの再起動（Linux は systemctl restart docker、Windows は Restart-Service com.docker.service、macOS/Windows の Desktop UI でも同様）を実施。
CI/CD パイプラインでは上記手順をスクリプト化し、失敗したらビルドを中止するフローを組むと、環境差異による不具合が防げます。
ツール側（TestContainers・Traefik 等）でも API バージョンロック が行われていることがあるため、設定ファイルや最新版への更新で対処。

これらの手順を体系的に実施すれば、Docker クライアントとデーモン間の API バージョン不整合エラーは 確実に解消 でき、安定した開発・CI 環境を維持できます。