What causes "serious error: graph has cycle ! " in apache/dolphinscheduler?

Detect the cycle before sorting: call dag.topologicalSortImpl() or check hasCycle-ish logic / use DagHelper to validate the workflow's dependencies and reject cyclic definitions.

apache/dolphinscheduler · critical · Exception

serious error: graph has cycle !

Error message

serious error: graph has cycle !

What it means

DAG.topologicalSort() performs a topological ordering of the graph; if the underlying graph contains a directed cycle, no topological order exists and it throws Exception("serious error: graph has cycle ! "). This usually indicates a malformed workflow dependency graph — in DolphinScheduler this should have been caught earlier by cycle detection, so it is treated as a serious invariant violation.

Source

Thrown at dolphinscheduler-common/src/main/java/org/apache/dolphinscheduler/common/graph/DAG.java:340

    }

    /**
     * Only DAG has a topological sort
     *
     * @return topologically sorted results, returns false if the DAG result is a ring result
     * @throws Exception errors
     */
    public List<Node> topologicalSort() throws Exception {
        lock.readLock().lock();

        try {
            Map.Entry<Boolean, List<Node>> entry = topologicalSortImpl();

            if (entry.getKey()) {
                return entry.getValue();
            }

            throw new Exception("serious error: graph has cycle ! ");
        } finally {
            lock.readLock().unlock();
        }
    }

    /**
     * if tho node does not exist,add this node
     *
     * @param node node
     * @param nodeInfo node information
     */
    private void addNodeIfAbsent(Node node, NodeInfo nodeInfo) {
        if (!containsNode(node)) {
            addNode(node, nodeInfo);
        }
    }

    /**

View on GitHub (pinned to 02eac45a1b)

Solutions

Detect the cycle before sorting: call dag.topologicalSortImpl() or check hasCycle-ish logic / use DagHelper to validate the workflow's dependencies and reject cyclic definitions.
Remove the circular dependency edge(s) from the input (fix task dependency configuration).
If you own the code, catch the Exception around topologicalSort() and surface a user-friendly 'circular dependency' error identifying the nodes involved.

Example fix

// before
List<Node> sorted = dag.topologicalSort(); // throws on cycles

// after
if (dag.hasCycle()) { // or try { dag.topologicalSort(); } catch (Exception e)
    throw new WorkflowException("Workflow tasks contain a circular dependency, cannot sort");
}
List<Node> sorted = dag.topologicalSort();

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate the workflow's dependency graph before building/sorting
DAG<String, String, String> dag = DagHelper.buildDagGraph(tasks);
if (dag.hasCycle()) { // or attempt topologicalSortImpl() and inspect the boolean
    throw new WorkflowException("Circular dependency detected among tasks");
}

Try / catch

try {
    List<Node> sorted = dag.topologicalSort();
} catch (Exception e) {
    throw new WorkflowException("Workflow task graph contains a cycle: " + e.getMessage(), e);
}

Prevention

Run cycle detection (DagHelper) when saving/importing workflow definitions so cyclic graphs never reach sort.
In the UI, prevent users from creating dependencies that loop back to upstream tasks.
Write unit tests for DAG construction with back-edge scenarios.

When it happens

Trigger: Calling dag.topologicalSort() (directly or via dag.nodeList()) on a DAG<String, ...> whose edges contain a cycle, e.g. A->B, B->A, added via addEdge or addEdgeIfAbsent.

Common situations: Workflow definitions with circular task dependencies (task A depends on B and B on A) slipped past validation; custom code builds a DAG manually and adds a back edge; DAG used as a general-purpose graph without acyclicity checks.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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