「Docker: 無効な参照形式」エラーの修正方法

Dockerを使えば、コンテナの構築、実行、管理が簡単になります。しかし、イメージの実行または構築時に「Invalid Reference Format（無効な参照フォーマット）」エラーが発生する場合があります。ほとんどの場合、これはイメージ名またはタグのフォーマットエラーが原因です。例えば、大文字、特殊文字、または値の欠落などが原因となる場合があります。このガイドでは、このエラーの一般的な原因と、再発を防ぐための修正方法について説明します。

「無効な参照形式」エラーを修正

「無効な参照形式」エラーの最も一般的な原因とその修正方法を見てみましょう。

画像名の大文字

Dockerではイメージ名を小文字にする必要があります。大文字を1文字でも使用するとフォーマットエラーが発生する可能性があります。例えば、以下のコマンドを実行するとエラーが発生します。

docker pull NGINX

「Docker: 無効な参照形式」エラーの修正方法 — アーカイブ名は小文字でなければなりません

このエラーを回避するには、コマンドを実行する前に、イメージ名が小文字であることを必ず確認してください。

docker pull nginx

特殊文字または無効な文字

ユーザーが誤ってDockerで許可されていない文字を追加してしまうことがあります。これには、@記号、スペース、あるいはWebサイトやドキュメントからコピーした、一見正常に見えるものの実際には正しくない文字などが含まれます。

たとえば、次のコマンドには特殊文字 @ が含まれているため、次のエラーが発生します。

docker run ubuntu@:latest

このエラーを修正するには、コマンドに余分な文字やフォーマットの問題がないことを確認してください。必要に応じて、プレーンテキストエディタを使用してコマンドを確認し、修正することもできます。

docker run ubuntu:latest

タグなしのコロン

よくある間違いの一つは、イメージ名の末尾にコロンを付けながらタグを付けないことです。例えば、Node.js をプルするには、次のコマンドを試してみましょう。

docker pull node:

Dockerは、コロンの後に、例えば Latest 、 18-alpine 、その他の有効なタグなどの値を指定します。値が指定されていない場合、イメージ名は不完全とみなされ、「無効な参照形式」エラーが発生します。

このエラーを修正するには、コロンの後に適切なタグを追加して、イメージ名を完全かつ有効なものにします。

docker pull node:latest

ファイルパスまたはボリュームマウントにスペースが含まれています

スペースを含むファイルパス、特に -v （ボリュームマウント）などのオプションを指定すると、Docker はパスの一部を別の引数として、あるいはイメージ名の一部として誤って解釈することがあります。その結果、以下に示すような予期しない結果が発生する可能性があります。

docker run -v /home/user/My Folder:/app ubuntu

これを回避するには、次に示すように、ファイルパスを常にスペースを含む二重引用符で囲みます。

docker run -v "/home/user/My Folder:/app" ubuntu

「/home/user/My Folder」を、コンテナにマウントするディレクトリへの実際のパスに置き換えます。

変数の不適切な使用

Docker を使用する場合、特にイメージのバージョンを指定する際に、コマンド内で変数を使用するのが一般的です。しかし、$VERSION などの変数が正しく設定されていないと、Docker で「無効な参照形式」エラーなどの問題が発生する可能性があります。

たとえば、Docker Hub から Ubuntu をプルするには、次のコマンドを実行します。

docker pull ubuntu:$VERSION

ここで、$VERSION はプルする Ubuntu イメージのバージョンを表すはずです。しかし、この変数に値を指定しないと、Docker はコマンドを「docker pull ubuntu:」と解釈してしまいます。その結果、コロンで終わり、必要なバージョンタグがないため、イメージ名は無効になります。

これを回避するには、コマンドで使用されるすべての変数が適切に定義されていることを確認してください。Linuxでは、次の構文を使用して変数を設定できます。

$VERSION=latest

次に、次のコマンドを実行して、指定されたバージョンをプルします。

docker pull ubuntu:$VERSION

Windows CMD では、set キーワードを使用して変数 (version など) を定義し、%VARIABLE%構文を使用してdocker pull などのコマンドでそれを参照する必要があります。

set VERSION=latest
docker pull ubuntu:%VERSION%

ここで、$VERSION は最新の値を保持しているため、Docker は問題なくubuntu:latestイメージをプルします。必要に応じて、18.04 などの特定のバージョンを指定することもできます。

コピー＆ペーストの問題

ユーザーはオンラインチュートリアルやドキュメントからコマンドをコピーすることがあります。コピーしたコマンドには、非表示のスペース、英語以外の句読点、特殊な引用符などの隠し文字が含まれている場合があります。これらの文字は、Dockerコマンドを意図せず破損させる可能性があります。

これを回避するには、可能な場合はコマンドを自分で入力するか、最初にコマンドをプレーンテキストエディターに貼り付けて、不要な書式を削除することをお勧めします。

Dockerで「無効な参照形式」エラーが発生する一般的な原因とその解決方法がわかったので、今後この問題を回避するための準備が整いました。大文字小文字のチェックから変数の正しい設定まで、これらの簡単なヒントは多くの時間とストレスを節約するのに役立ちます。さらに詳しく知りたい場合は、カスタムDockerイメージにタグを付けてレジストリにプッシュする方法や、使用していないイメージをクリーンアップしてシステムをクリーンな状態に保つ方法も学ぶとよいでしょう。

Tags: #System