conductor-oss/conductor · error · IllegalArgumentException

NULL input passed when starting workflow

Error message

NULL input passed when starting workflow

What it means

Thrown by validateWorkflow() when both workflowInput is null AND externalStoragePath is blank. Conductor requires every workflow to have input — either inline (the workflowInput map) or referenced by an external storage URI (e.g., an S3 path). Starting with neither means the workflow's tasks will receive null input, leading to downstream failures. The method also records a workflow start error metric before throwing.

Source

Thrown at core/src/main/java/com/netflix/conductor/core/execution/WorkflowExecutorOps.java:2809

        return workflow;
    }

    /**
     * Performs validations for starting a workflow
     *
     * @throws IllegalArgumentException if the validation fails.
     */
    private void validateWorkflow(
            WorkflowDef workflowDef,
            Map<String, Object> workflowInput,
            String externalStoragePath) {
        // Check if the input to the workflow is not null
        if (workflowInput == null && StringUtils.isBlank(externalStoragePath)) {
            LOGGER.error("The input for the workflow '{}' cannot be NULL", workflowDef.getName());
            Monitors.recordWorkflowStartError(
                    workflowDef.getName(), WorkflowContext.get().getClientApp());

            throw new IllegalArgumentException("NULL input passed when starting workflow");
        }
    }

    private void notifyWorkflowStatusListener(WorkflowModel workflow, WorkflowEventType event) {
        try {
            switch (event) {
                case STARTED:
                    workflowStatusListener.onWorkflowStartedIfEnabled(workflow);
                    break;
                case RERAN:
                    workflowStatusListener.onWorkflowRerunIfEnabled(workflow);
                    break;
                case RETRIED:
                    workflowStatusListener.onWorkflowRetriedIfEnabled(workflow);
                    break;
                case PAUSED:
                    workflowStatusListener.onWorkflowPausedIfEnabled(workflow);
                    break;

View on GitHub (pinned to cf7c3e4a8a)

Solutions

1. Provide a non-null workflowInput map (even an empty {} map satisfies the check).
2. If input is large, set externalInputPayloadStoragePath to a valid external storage URI (e.g., s3://bucket/key).
3. Ensure your client SDK or REST caller always includes an input field — check for accidental null serialization.
4. If the workflow genuinely needs no input, pass an empty Map: Map.of().

Example fix

// before
StartWorkflowInput input = StartWorkflowInput.builder()
    .name("myWorkflow")
    .workflowInput(null)
    .build();

// after
StartWorkflowInput input = StartWorkflowInput.builder()
    .name("myWorkflow")
    .workflowInput(new HashMap<>())  // or Map.of()
    .build();

// Ensure input is provided before starting
Map<String, Object> input = input.getWorkflowInput();
if (input == null && StringUtils.isBlank(input.getExternalInputPayloadStoragePath())) {
    input.setWorkflowInput(new HashMap<>()); // default to empty map
}
workflowExecutor.startWorkflow(input);

When it happens

Trigger: Calling startWorkflow / startWorkflowIdempotent with a null workflowInput map and no externalInputPayloadStoragePath. Passing an empty StartWorkflowInput where both getWorkflowInput() returns null and getExternalInputPayloadStoragePath() is blank.

Common situations: Workflow definition has no schemaVersion or input schema, and the caller omits input entirely. External storage path field is misconfigured or left empty. A client SDK serializes an empty input object as null rather than an empty map.

Related errors

• workflowDefinition is a string, but not a valid DSL string
• workflowDefinition must be either null, or WorkflowDef, or a
• priority MUST be between 0 and 99 (inclusive)
• Model string cannot be null or empty
• Invalid model format: '%s'. Expected 'provider/model'.

AI-assisted analysis of conductor-oss/conductor@cf7c3e4a8a (2026-08-14). Data as JSON: /api/errors/d846a3d885ce385e. Report an issue: GitHub.