なぜこのエラーが発生するのか
通常、このエラーはルーチンコマンドの実行時に発生します。docker ps や docker-compose up を実行した際、コンテナが表示される代わりにバージョン不一致のエラーが表示されます。これは、Dockerがクライアント・サーバーアーキテクチャを採用しているために起こります。Client（クライアント）は手元のターミナルツールであり、Server（サーバー、またはデーモン）はコンテナを実行するエンジンです。
これら2つはREST APIを介して通信します。最近Docker Desktopをバージョン4.28以上にアップデートした場合、クライアントのAPIバージョンは恐らく1.44にアップグレードされています。しかし、リモートサーバーがDocker 20.10.xのような古いバージョンを実行している場合、API 1.41までしか理解できません。サーバーは、クライアントが使用しようとしている新しい機能を認識できないため、接続を拒否します。
解決策1：クライアントに古いAPIの使用を強制する
最も早い修正方法は、追加のインストールを必要としません。Docker CLIに対して、サーバーのレベルに合わせて「ダウングレードして通信する」ように指示できます。Dockerは後方互換性を維持するように設計されているため、この方法は安全かつ効果的です。
LinuxおよびmacOS
現在のターミナルセッションの環境変数を次のように設定します：
export DOCKER_API_VERSION=1.41
この設定を永続化させるには、シェルプロファイルに追加します。Zshユーザーの場合は、次のコマンドを実行してください：
echo 'export DOCKER_API_VERSION=1.41' >> ~/.zshrc
source ~/.zshrc
Windows (PowerShell)
PowerShellで作業している場合は、一時的な修正として次のコマンドを使用します：
$env:DOCKER_API_VERSION = "1.41"
恒久的に変更するには、スタートメニューを開き「システム環境変数の編集」を検索します。DOCKER_API_VERSION という名前の新しい変数を作成し、値を 1.41 に設定します。
解決策2：Docker Engineをアップグレードする
サーバーへのSSHアクセス権がある場合は、エンジンのアップグレードが長期的に見て最善の策です。これにより、最新のセキュリティパッチとパフォーマンスの向上が保証されます。UbuntuまたはDebianサーバーでは、約30秒で完了します：
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io
sudo systemctl restart docker
アップデートが完了すると、サーバーは新しいAPIをサポートするようになり、エラーは解消されます。
解決策3：Docker Compose V2の取り扱い
モダンなDocker Compose（docker compose コマンド）は、通常 DOCKER_API_VERSION 変数を自動的に尊重します。もし古いスタンドアロンの docker-compose バイナリを使用している場合は、挙動が異なる可能性があります。レガシーな問題を避けるために、Docker Compose V2プラグインへの移行をお勧めします。
確認：うまくいきましたか？
次のコマンドを実行して、接続状態を確認します：
docker version
API version フィールドを確認してください。ClientとServerの両方に互換性のある数値が表示されているはずです。両方が1.41と表示されていれば、準備完了です。
Client:
API version: 1.41
Server:
Engine:
API version: 1.41 (minimum version 1.12)
予防のためのプロのヒント
- 環境を一致させる： ローカルのDockerバージョンを、本番サーバーのマイナーリリースから1つか2つ以内に保つようにしてください。
- CI/CDの整合性： GitHub ActionsやGitLabランナーでこのエラーが発生した場合は、パイプラインのYAMLで使用されている
docker-imageのバージョンを確認してください。 - プロジェクト固有のバージョン： プロジェクトフォルダに
COMPOSE_API_VERSION=1.41を記述した.envファイルを置くことができます。これにより、チーム全員がその特定のプロジェクトに対して同じAPIバージョンを使用するように強制できます。