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

- **ID:** `docker/healthcheck-command-not-found`
- **Domain:** docker
- **Category:** config_error
- **Verification:** ai_generated
- **Fix Rate:** 92%

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

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Docker 20.10.21 | active | — | — |
| Docker 24.0.6 | active | — | — |
| Docker 25.0.2 | active | — | — |

## Workarounds

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

## Dead Ends

- **** — The HEALTHCHECK command runs inside the container, so the script must be present in the image filesystem; the build context alone is insufficient. (70% 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 '.'. (85% fail)
- **** — Many minimal base images (e.g., alpine, distroless) do not include curl, causing a 'not found' error for the healthcheck command. (60% fail)