{
  "id": "cicd/docker-buildkit-ssh-auth-fail",
  "signature": "ERROR: failed to solve: failed to fetch oauth token: unexpected status from POST request to https://ghcr.io/token: 401 Unauthorized",
  "signature_zh": "错误：解析失败：获取OAuth令牌失败：向 https://ghcr.io/token 发送POST请求返回意外状态：401 未授权",
  "regex": "failed to fetch oauth token.*401 Unauthorized",
  "domain": "cicd",
  "category": "auth_error",
  "subcategory": null,
  "root_cause": "Docker BuildKit fails to authenticate with a container registry (e.g., GitHub Container Registry) because the SSH agent forwarding or registry credentials are not properly configured for the build context.",
  "root_cause_type": "generic",
  "root_cause_zh": "Docker BuildKit 无法通过容器注册表（如 GitHub Container Registry）的身份验证，因为 SSH 代理转发或注册表凭据未在构建上下文中正确配置。",
  "versions": [
    {
      "version": "Docker 24.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Docker 25.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "BuildKit v0.12",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Docker Desktop 4.25",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "The issue is authentication, not cache. Pruning removes cached layers but does not provide credentials.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "--no-cache only skips layer caching; it does not inject credentials into the build context.",
      "fail_rate": 0.75,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "BuildKit may not inherit the Docker CLI credentials; it uses its own credential helpers.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Pass registry credentials via Docker BuildKit secrets or --secret flag: echo $GITHUB_TOKEN | docker build --secret id=gh_token,env=GITHUB_TOKEN -t myimage . and use RUN --mount=type=secret,id=gh_token in Dockerfile to authenticate.",
      "success_rate": 0.85,
      "how": "Pass registry credentials via Docker BuildKit secrets or --secret flag: echo $GITHUB_TOKEN | docker build --secret id=gh_token,env=GITHUB_TOKEN -t myimage . and use RUN --mount=type=secret,id=gh_token in Dockerfile to authenticate.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use DOCKER_AUTH_CONFIG environment variable with a base64-encoded JSON config for the registry, which BuildKit reads automatically.",
      "success_rate": 0.8,
      "how": "Use DOCKER_AUTH_CONFIG environment variable with a base64-encoded JSON config for the registry, which BuildKit reads automatically.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Configure a .docker/config.json file in the build context with the registry credentials, ensuring it is not exposed in the final image by using a .dockerignore.",
      "success_rate": 0.75,
      "how": "Configure a .docker/config.json file in the build context with the registry credentials, ensuring it is not exposed in the final image by using a .dockerignore.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Pass registry credentials via Docker BuildKit secrets or --secret flag: echo $GITHUB_TOKEN | docker build --secret id=gh_token,env=GITHUB_TOKEN -t myimage . and use RUN --mount=type=secret,id=gh_token in Dockerfile to authenticate.",
    "Use DOCKER_AUTH_CONFIG environment variable with a base64-encoded JSON config for the registry, which BuildKit reads automatically.",
    "Configure a .docker/config.json file in the build context with the registry credentials, ensuring it is not exposed in the final image by using a .dockerignore."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://docs.docker.com/build/ci/github-actions/#authentication",
  "official_doc_section": null,
  "error_code": "BUILDKIT_AUTH_FAIL",
  "verification_tier": "ai_generated",
  "confidence": 0.84,
  "fix_success_rate": 0.78,
  "resolvable": "partial",
  "first_seen": "2024-03-20",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}