拉取镜像提示 TAG_INVALID 或无效标签（400）怎么办？
本文适用于：
- • 拉取或推送时出现 HTTP
400与标签校验失败 - • 报错含
TAG_INVALID、无效标签、'None'/'null' - • CI/CD、脚本或 Helm 模板中镜像 tag 变量未正确赋值
- • 标签长度超过 Docker Registry 规定的 128 字符上限
先搞清一点：这是标签字符串本身不合法，与镜像源无关
Registry 在收到拉取或推送请求时，会先校验 tag 格式。若 tag 为空、为 Python/JSON 的 None/null 字面量、含非法字符或超长， 会直接返回 400 Bad Request 与 TAG_INVALID，不会进入真正的 manifest 查询阶段。
典型报错示例
docker pull docker.xuanyuan.run/library/nginx:None
Error response from daemon: invalid reference format
Error response from daemon: manifest for nginx:null not found: manifest unknown: TAG_INVALID: invalid tag 'null'
unexpected status ... 400 Bad Request
TAG_INVALID: tag length exceeds maximum of 128 characters
常见原因
- CI/CD 变量为空：Jenkins、GitLab CI、GitHub Actions 中
${IMAGE_TAG}未设置，模板展开后变成:None或空 tag - 脚本语言默认值泄露：Python 中
str(None)→"None"；JSON 中null被直接拼进镜像名 - 错误使用 digest 与 tag：同一引用中同时写 tag 与
@sha256:...，或 tag 部分留空 - 标签过长：将完整 Git commit 说明、构建 URL 等拼进 tag，超过 Registry 规定的 128 字符 上限
- 含非法字符：tag 中不宜包含空格、
:、@等（digest 应使用repo@sha256:...形式，而非当作 tag）
处理建议
1）打印实际执行的镜像全名
在 CI 日志或脚本中输出最终镜像引用，确认 tag 部分不是空、None、null：
# 示例：部署前 echo 检查
echo "IMAGE=${IMAGE_NAME}:${IMAGE_TAG}"
docker pull "${IMAGE_NAME}:${IMAGE_TAG}"
2）为 tag 设置合理默认值或校验
- 使用 Git commit 短 SHA（如
abc1234）或语义化版本（v1.2.3），避免裸latest以外的空值 - 在流水线中增加判断：
if [ -z "$IMAGE_TAG" ]; then exit 1; fi - Python 拼接前检查：
if tag is None: raise ValueError(...)
3）控制 tag 长度与字符集
tag 最长 128 字符；仅使用小写字母、数字、.、_、- 等合法字符。 需要固定版本时，优先用 digest 拉取（见 digest 校验说明）。
与相近错误的区分
- 400 TAG_INVALID：tag 字符串格式非法（空、None、超长等）→ 修脚本/变量
- manifest unknown：tag 格式合法，但仓库中不存在该标签 → 核对镜像名与 tag
- 422 Unknown：上游查询 manifest 时异常 → 按该文排查 Hub 状态与老镜像问题
你可能还会遇到：
本文由「轩辕镜像」维护
轩辕镜像 | 国内 Docker 镜像加速
内容基于轩辕镜像真实用户使用与实测整理