flowable/flowable-engine · error · FlowableException

Could not execute shell command for + execution

Error message

Could not execute shell command for + execution

What it means

Flowable's ShellActivityBehavior runs an external shell command from a BPMN service task and writes the exit code to an optional result variable. Any exception while creating or executing the process (bad command path, IO problems, interrupted waits) is wrapped in this FlowableException, keeping the original as the cause. It signals the shell invocation itself failed, not a business-logic error.

Solutions

  1. Verify the shell command/executable exists and is executable on the machine running the Flowable engine (or in the container image)
  2. Inspect the wrapped cause exception (getCause()) for the exact OS-level failure
  3. Log/validate the command and arguments by reading ShellActivityBehavior fields before deployment; test the exact command manually as the engine's OS user
  4. Set the extension attributes (command, args, wait, outputVariable, errorCodeVariable) correctly in the BPMN XML
  5. If the process should not be killed by a failing command, add an error boundary event on the shell service task

Example fix

// before
<flowable:field name="command" stringValue="my-script.sh" />
// after
<flowable:field name="command" stringValue="/opt/scripts/my-script.sh" />
Defensive patterns

Strategy: try-catch

Validate before calling

File script = new File(commandPath);
if (!script.exists() || !script.canExecute()) {
    throw new IllegalStateException("Shell command not executable: " + commandPath);
}

Try / catch

try {
    execution.setVariable("result", runShell(...));
} catch (FlowableException e) {
    logger.error("Shell command failed", e.getCause());
    throw new BpmnError("SHELL_FAILED", e.getCause().getMessage());
}

Prevention

When it happens

Trigger: Shell task configured with a command/executable that does not exist or is not on PATH; working directory missing; argument array invalid; IO streams fail; Runtime.exec throws; reading output or writing the error-code variable throws.

Common situations: Deploying processes that run 'sh script.sh' where the script was never deployed to the server; container images without the required binary; permission errors on the executable; arguments containing spaces due to misconfigured expression results.

Related errors

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/83316a72efc6c495. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/behavior/ShellActivityBehavior.java:137

            Process process = processBuilder.start();

            if (waitFlag) {
                int errorCode = process.waitFor();

                if (resultVariableStr != null) {
                    String result = convertStreamToStr(process.getInputStream());
                    execution.setVariable(resultVariableStr, result);
                }

                if (errorCodeVariableStr != null) {
                    execution.setVariable(errorCodeVariableStr, Integer.toString(errorCode));

                }

            }
        } catch (Exception e) {
            throw new FlowableException("Could not execute shell command for " + execution, e);
        }

        leave(execution);
    }

    public static String convertStreamToStr(InputStream is) throws IOException {

        if (is != null) {
            Writer writer = new StringWriter();

            char[] buffer = new char[1024];
            try (Reader reader = new BufferedReader(new InputStreamReader(is, StandardCharsets.UTF_8))) {
                int n;
                while ((n = reader.read(buffer)) != -1) {
                    writer.write(buffer, 0, n);
                }
            }
            return writer.toString();

View on GitHub (pinned to d6d39ce1c6)