{"record":{"id":"21dda718a06e4fc9","repo":"testcontainers/testcontainers-java","slug":"exception-when-executing-joinedcommand","errorCode":null,"errorMessage":"Exception when executing ${joinedCommand}","messagePattern":"Exception when executing (.+?)","errorType":"exception","errorClass":"ShellCommandException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/testcontainers/utility/CommandLine.java","lineNumber":40,"sourceCode":"\n    private static final Logger LOGGER = LoggerFactory.getLogger(CommandLine.class);\n\n    /**\n     * Run a shell command synchronously.\n     *\n     * @param command command to run and arguments\n     * @return the stdout output of the command\n     */\n    public static String runShellCommand(String... command) {\n        String joinedCommand = String.join(\" \", command);\n        LOGGER.debug(\"Executing shell command: `{}`\", joinedCommand);\n\n        try {\n            ProcessResult result = new ProcessExecutor().command(command).readOutput(true).exitValueNormal().execute();\n\n            return result.outputUTF8().trim();\n        } catch (IOException | InterruptedException | TimeoutException | InvalidExitValueException e) {\n            throw new ShellCommandException(\"Exception when executing \" + joinedCommand, e);\n        }\n    }\n\n    /**\n     * Check whether an executable exists, either at a specific path (if a full path is given) or\n     * on the PATH.\n     *\n     * @param executable the name of an executable on the PATH or a complete path to an executable that may/may not exist\n     * @return  whether the executable exists and is executable\n     */\n    public static boolean executableExists(String executable) {\n        // First check if we've been given the full path already\n        File directFile = new File(executable);\n        if (directFile.exists() && directFile.canExecute()) {\n            return true;\n        }\n\n        for (String pathString : getSystemPath()) {","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/utility/CommandLine.java#L22-L58","documentation":"CommandLine.runShellCommand executes an external command via ProcessExecutor and returns its UTF-8 stdout. When the command fails to run or complete — non-zero exit (InvalidExitValueException), timeout, I/O error, or interruption — it wraps the cause in ShellCommandException including the joined command line. It signals that an external helper binary could not be executed successfully.","triggerScenarios":"Any Testcontainers path invoking a local command (e.g. docker-machine/other CLI probes) where the binary is missing, exits non-zero, hangs past the timeout, or the JVM thread is interrupted.","commonSituations":"Required CLI not installed or not on PATH; script with non-zero exit; slow machine hitting the process timeout; command prompting for input; shutdown interrupts mid-execution.","solutions":["Run the joined command from the message manually in a shell to reproduce and see the real failure.","Install the missing binary or fix PATH so the command resolves.","Fix the command so it exits 0 (or check why Testcontainers calls it); ensure the environment is non-interactive.","Check for JVM shutdown/thread interruption if the cause is InterruptedException."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// verify the external command exists before Testcontainers calls it\nProcess which = new ProcessBuilder(\"which\", \"<tool>\").start();\nif (which.waitFor() != 0) throw new IllegalStateException(\"<tool> not on PATH\");","typeGuard":null,"tryCatchPattern":"try {\n    String out = CommandLine.runShellCommand(cmd...);\n} catch (ShellCommandException e) {\n    log.error(\"External command failed: {} cause: {}\", e.getMessage(), e.getCause());\n    // fall back or rethrow with environment guidance\n}","preventionTips":["Install and PATH-export any CLIs the library shells out to","Run commands in CI before tests to fail fast","Avoid interrupting JVM/threads during container startup","Check exit codes by reproducing the command manually"],"tags":["process","shell","command-execution"],"backgroundTag":"command-not-found","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}