docker config_error ai_generated true

Error: Container health check command not found: /healthcheck.sh: No such file or directory

ID: docker/healthcheck-command-not-found

Also available as: JSON · Markdown · 中文
92%Fix Rate
87%Confidence
1Evidence
2025-01-12First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
Docker 20.10.21 active — — —
Docker 24.0.6 active — — —
Docker 25.0.2 active — — —

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.

generic

中文

Dockerfile 中的 HEALTHCHECK 指令引用了容器镜像中指定路径下不存在的脚本或二进制文件。

Official Documentation

https://docs.docker.com/engine/reference/builder/#healthcheck

Workarounds

  1. 95% success 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 
    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
  2. 90% success 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 
    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
  3. 88% success If using a shell command without a script, use the 'CMD-SHELL' form: HEALTHCHECK --interval=30s CMD-SHELL pgrep nginx || exit 1 
    If using a shell command without a script, use the 'CMD-SHELL' form: HEALTHCHECK --interval=30s CMD-SHELL pgrep nginx || exit 1

中文步骤

  1. 确保健康检查脚本在 HEALTHCHECK 行之前通过 COPY 指令复制到镜像中。示例：COPY healthcheck.sh /healthcheck.sh && HEALTHCHECK --interval=30s --timeout=3s CMD /healthcheck.sh
  2. 使用内置命令如 'curl' 或 'wget' 进行健康检查，并在 Dockerfile 中安装它们。示例：RUN apt-get update && apt-get install -y curl && HEALTHCHECK CMD curl -f http://localhost/ || exit 1
  3. 如果使用不带脚本的 shell 命令，使用 'CMD-SHELL' 形式：HEALTHCHECK --interval=30s CMD-SHELL pgrep nginx || exit 1

Dead Ends

Common approaches that don't work:

  1. 70% fail

    The HEALTHCHECK command runs inside the container, so the script must be present in the image filesystem; the build context alone is insufficient.

  2. 85% fail

    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 '.'.

  3. 60% fail

    Many minimal base images (e.g., alpine, distroless) do not include curl, causing a 'not found' error for the healthcheck command.