docker『Invalid Reference Format』の原因と対処法

[registryhost/][namespace/]repository[:tag][@digest]

# 例
nginx:1.25
docker.io/library/nginx:1.25
ghcr.io/myorg/myapp:2025-11-01

# NG: スペースでtagが別引数になっている
docker run myapp: latest

# NG: レジストリとポートとタグがぐちゃっと混ざっている
docker run myregistry:5000/myapp:1:2

# NG: 大文字や空白を含むリポジトリ名
docker build -t MyApp Image:latest 

# OK: tagを1つにまとめ、名前は小文字で
docker run myapp:latest
docker run myregistry:5000/myapp:1.2

# OK: build時も正しい書式で
docker build -t myorg/myapp:2025-11-01 .

# NG: build の -t の直後にスペースを入れてしまう
docker build -t myorg/myapp :latest .

# NG: -t の引数をクォートせず、shell展開で壊す
TAG=2025-11-01 debug
docker build -t myorg/myapp:$TAG debug .

# OK: -t の引数を1つの文字列にする
docker build -t myorg/myapp:2025-11-01 .

# OK: shell変数の場合もコロンを含めて1つのトークンにする
TAG=2025-11-01
docker build -t myorg/myapp:${TAG} .

# NG: docker run で env 変数をそのままイメージ名として使って壊す
export IMAGE="myorg/myapp"      # tag なし
docker run $IMAGE:             # : の後ろが空でエラー

# OK: デフォルトtagを決めて組み立てる
export IMAGE="myorg/myapp"
export TAG="2025-11-01"
docker run ${IMAGE}:${TAG}

# NG例: imageの中で変な文字を混ぜてしまう
services:
  app:
    image: myorg/myapp: latest   # ← スペース入り


# OK例: 1つの文字列として正しく書く
services:
  app:
    image: myorg/myapp:latest

# NG: コロンを環境変数に含め忘れて組み立てが壊れる
services:
  app:
    image: ${IMAGE_NAME}:${IMAGE_TAG:-latest}

# IMAGE_NAME="myorg/myapp:" などとなっていると二重コロンでエラー

# OK: repository と tag を分けて管理して組み立て
# .env
IMAGE_REPO=myorg/myapp
IMAGE_TAG=2025-11-01

# docker-compose.yml
services:
  app:
    image: "${IMAGE_REPO}:${IMAGE_TAG}"

# NG: コマンド置換の結果にスペースが含まれている例
docker run $(cat image.txt)

# image.txt の中身: "myorg/myapp:2025-11-01 latest"
# → 2引数に割れて invalid reference format

# OK: ファイルから「イメージ名だけ」を取るか、1行1件にする
IMAGE=$(head -n1 image.txt | awk '{print $1}')
docker run "$IMAGE"

# NG: 空の環境変数で末尾コロンだけになる
TAG=
docker run myorg/myapp:$TAG    # → "myorg/myapp:" となりエラー

# OK: デフォルト値を使う
TAG=${TAG:-latest}
docker run myorg/myapp:${TAG}

# 正しい構造
<registryhost>[:port]/<namespace>/<repo>[:tag]

# OK例
myregistry:5000/myorg/myapp:2025-11-01

# NG: コロンを2回以上使ってしまう
myregistry:5000:443/myorg/myapp:1.0       # レジストリホストが不正
myregistry:5000/myorg/myapp:1:0           # tagが不正

# NG
myOrg/MyApp        # 大文字
my org/myapp       # スペース
myorg/myapp#2025   # # を含む

# OK
myorg/myapp
myorg/myapp_v2
myorg/myapp-2025.11

# 例: GitHub Actions などのスクリプトでイメージ名を組み立てる
REPO="ghcr.io/myorg/myapp"
TAG="${GITHUB_SHA:-dev}"          # commit hash など
IMAGE="${REPO}:${TAG}"

echo "Building ${IMAGE}"
docker build -t "${IMAGE}" .
docker push "${IMAGE}"

# 1) docker が「イメージ名として解釈する文字列」を echo で出して確認
IMAGE="myorg/myapp:2025-11-01"
echo "Using image: '${IMAGE}'"
docker run "${IMAGE}"            # ここでInvalid reference formatならIMAGE自体が不正

# 2) docker image inspect で形式を確認（存在確認も兼ねる）
docker image inspect "${IMAGE}" >/dev/null && echo "valid" || echo "invalid"

# 3) docker-compose.yml を展開して確認
docker compose config | sed -n '/image:/p'

# NG: スペース入り
docker run myorg/myapp: latest
# OK
docker run myorg/myapp:latest

# NG: 末尾コロン
docker run myorg/myapp:
# OK: tagを入れる or 省略してlatest
docker run myorg/myapp:2025-11-01
docker run myorg/myapp

# NG: 大文字リポジトリ
docker build -t MyOrg/MyApp:1.0 .
# OK: 小文字に統一
docker build -t myorg/myapp:1.0 .

# NG: レジストリ+ポート+タグがぐちゃぐちゃ
docker run myregistry:5000/myapp:1:2
# OK
docker run myregistry:5000/myapp:1.2