apache/dolphinscheduler · error · java.lang.IllegalArgumentException

The branch is empty, please check the switch task configurat

Error message

The branch is empty, please check the switch task configuration

What it means

Thrown by SwitchLogicTask.checkIfBranchExist when the switch task's selected branch node code is null. The switch plugin resolves which branch to take from SwitchParameters.SwitchResult; if no branch (neither a matched condition nor the default next node) was produced, it refuses to run. This is treated as a misconfiguration of the switch task, not a runtime failure, so it surfaces as IllegalArgumentException during task start.

Source

Thrown at dolphinscheduler-master/src/main/java/org/apache/dolphinscheduler/server/master/engine/executor/plugin/switchtask/SwitchLogicTask.java:128

                    break;
                }
            } catch (Exception e) {
                log.info("Execute switch item: {} failed", switchResultVo, e);
            }
        }

        if (nextBranch == null) {
            log.info("All switch item is not satisfied");
            moveToDefaultBranch();
        } else {
            log.info("The condition is satisfied, move to the next branch: {}", getTaskName(nextBranch));
            taskParameters.setNextBranch(nextBranch);
        }
    }

    private void checkIfBranchExist(Long branchNode) {
        if (branchNode == null) {
            throw new IllegalArgumentException("The branch is empty, please check the switch task configuration");
        }
        if (workflowExecution.getWorkflowExecuteContext().getWorkflowGraph()
                .getTaskNodeByCode(branchNode) == null) {
            throw new IllegalArgumentException(
                    "The branch(code= " + branchNode
                            + ") is not in the dag, please check the switch task configuration");
        }
    }

    private String getTaskName(Long taskCode) {
        return Optional.ofNullable(workflowExecution.getWorkflowExecuteContext())
                .map(IWorkflowExecuteContext::getWorkflowGraph)
                .map(iWorkflowGraph -> iWorkflowGraph.getTaskNodeByCode(taskCode))
                .map(TaskDefinition::getName)
                .orElse(null);
    }

    @Override

View on GitHub (pinned to 02eac45a1b)

Solutions

Open the switch task definition and set the default branch (nextNode) so a branch always exists when no condition matches.
Verify each SwitchResult dependTaskList entry has a valid nextNode pointing at a task in the same workflow.
Re-save the task via the UI/API so taskParams JSON is regenerated correctly, then re-run the workflow.

Example fix

// before: switch params with no default branch
{"switchResult":{"dependTaskList":[{"condition":"${var}>1","nextNode":null}]}}
// after: add a default nextNode
{"switchResult":{"dependTaskList":[{"condition":"${var}>1","nextNode":1234567890}],"nextNode":9876543210}}

Defensive patterns

Strategy: validation

Validate before calling

// before running a switch task, validate its params
SwitchParameters p = JSONUtils.parseObject(taskInstance.getTaskParams(), SwitchParameters.class);
boolean ok = p != null && p.getSwitchResult() != null && p.getSwitchResult().getNextNode() != null;
if (!ok) throw new IllegalStateException("Switch task has no default branch configured");

Try / catch

try {
    switchLogicTask.start();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("The branch is empty")) {
        // alert: switch task misconfigured; fix branch config
    } else throw e;
}

Prevention

Always configure the default branch (nextNode) on switch tasks in the UI.
Validate switch task params JSON when saving via API or scripts.
Review workflow definitions for switch tasks after import/export.

When it happens

Trigger: Calling start() on a switch logic task whose computed nextBranch is null — e.g. SwitchParameters with an empty switchResult, no dependTaskList entry whose condition matches, and no nextNode/default branch set.

Common situations: Users create a switch task in the UI but never configure the default branch after the last condition; JSON task params exported/edited by hand omit nextNode; conditions defined all evaluate false with no fallback branch wired in the DAG.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/a7c1a1e01f0e1c57. Report an issue: GitHub.