{
  "id": "docker/healthcheck-command-not-found",
  "signature": "Error: Container health check command not found: /healthcheck.sh: No such file or directory",
  "signature_zh": "错误：容器健康检查命令未找到：/healthcheck.sh：没有那个文件或目录",
  "regex": "Container health check command not found: [\\w/.]+: No such file or directory",
  "domain": "docker",
  "category": "config_error",
  "subcategory": null,
  "root_cause": "The HEALTHCHECK instruction in the Dockerfile references a script or binary that does not exist inside the container image at the specified path.",
  "root_cause_type": "generic",
  "root_cause_zh": "Dockerfile 中的 HEALTHCHECK 指令引用了容器镜像中指定路径下不存在的脚本或二进制文件。",
  "versions": [
    {
      "version": "Docker 20.10.21",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Docker 24.0.6",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Docker 25.0.2",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "The HEALTHCHECK command runs inside the container, so the script must be present in the image filesystem; the build context alone is insufficient.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "HEALTHCHECK does not support relative paths; it always interprets the command as an absolute path or a shell command. './healthcheck.sh' will be treated as a literal filename starting with '.'.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Many minimal base images (e.g., alpine, distroless) do not include curl, causing a 'not found' error for the healthcheck command.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Ensure the healthcheck script is copied into the image with a COPY instruction before the HEALTHCHECK line. Example: COPY healthcheck.sh /healthcheck.sh && HEALTHCHECK --interval=30s --timeout=3s CMD /healthcheck.sh",
      "success_rate": 0.95,
      "how": "Ensure the healthcheck script is copied into the image with a COPY instruction before the HEALTHCHECK line. Example: COPY healthcheck.sh /healthcheck.sh && HEALTHCHECK --interval=30s --timeout=3s CMD /healthcheck.sh",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use a built-in command like 'curl' or 'wget' for health checks, and install it in the Dockerfile if needed. Example: RUN apt-get update && apt-get install -y curl && HEALTHCHECK CMD curl -f http://localhost/ || exit 1",
      "success_rate": 0.9,
      "how": "Use a built-in command like 'curl' or 'wget' for health checks, and install it in the Dockerfile if needed. Example: RUN apt-get update && apt-get install -y curl && HEALTHCHECK CMD curl -f http://localhost/ || exit 1",
      "condition": "",
      "sources": []
    },
    {
      "action": "If using a shell command without a script, use the 'CMD-SHELL' form: HEALTHCHECK --interval=30s CMD-SHELL pgrep nginx || exit 1",
      "success_rate": 0.88,
      "how": "If using a shell command without a script, use the 'CMD-SHELL' form: HEALTHCHECK --interval=30s CMD-SHELL pgrep nginx || exit 1",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "确保健康检查脚本在 HEALTHCHECK 行之前通过 COPY 指令复制到镜像中。示例：COPY healthcheck.sh /healthcheck.sh && HEALTHCHECK --interval=30s --timeout=3s CMD /healthcheck.sh",
    "使用内置命令如 'curl' 或 'wget' 进行健康检查，并在 Dockerfile 中安装它们。示例：RUN apt-get update && apt-get install -y curl && HEALTHCHECK CMD curl -f http://localhost/ || exit 1",
    "如果使用不带脚本的 shell 命令，使用 'CMD-SHELL' 形式：HEALTHCHECK --interval=30s CMD-SHELL pgrep nginx || exit 1"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://docs.docker.com/engine/reference/builder/#healthcheck",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.87,
  "fix_success_rate": 0.92,
  "resolvable": "true",
  "first_seen": "2025-01-12",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}