alibaba/spring-ai-alibaba · error · BizException

WORKFLOW_CONFIG_INVALID

WORKFLOW_CONFIG_INVALID

Error message

Workflow must contain at least one start node with in-degree 0

What it means

During graph construction in WorkflowExecuteManager.constructGraph, the directed graph of workflow nodes must contain at least one source node (in-degree 0) to serve as the start. If every node has incoming edges, there is no entry point and WORKFLOW_CONFIG_INVALID is thrown.

Source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/workflow/runtime/WorkflowExecuteManager.java:419

		// Create a temporary WorkflowConfig to reuse the validation logic
		WorkflowConfig tempConfig = new WorkflowConfig();
		tempConfig.setNodes(nodes);
		tempConfig.setEdges(edges);
		DirectedAcyclicGraph<String, Edge> graph = constructGraph(tempConfig);

		// Check connectivity
		Set<String> sourceNodes = graph.vertexSet()
			.stream()
			.filter(nodeId -> graph.incomingEdgesOf(nodeId).isEmpty())
			.collect(Collectors.toSet());

		Set<String> sinkNodes = graph.vertexSet()
			.stream()
			.filter(nodeId -> graph.outgoingEdgesOf(nodeId).isEmpty())
			.collect(Collectors.toSet());

		if (sourceNodes.isEmpty()) {
			throw new BizException(ErrorCode.WORKFLOW_CONFIG_INVALID
				.toError("Workflow must contain at least one start node with in-degree 0"));
		}
		if (sinkNodes.isEmpty()) {
			throw new BizException(ErrorCode.WORKFLOW_CONFIG_INVALID
				.toError("Workflow must contain at least one end node with out-degree 0"));
		}

		// Check if all nodes are reachable from source nodes
		Set<String> reachableFromSource = new HashSet<>();
		for (String sourceNode : sourceNodes) {
			reachableFromSource.addAll(findReachableNodes(graph, sourceNode));
		}
		if (!reachableFromSource.equals(graph.vertexSet())) {
			throw new BizException(ErrorCode.WORKFLOW_CONFIG_INVALID
				.toError("There are nodes that cannot be reached from start nodes"));
		}

		// Check if all nodes can reach sink nodes

View on GitHub (pinned to f82da0b50f)

Solutions

1. Open the workflow in the editor and confirm exactly one Start node exists with no incoming edges.
2. Remove any edge that points into the start node or disconnect nodes so a node with in-degree 0 exists.
3. Break cycles: restructure loops using the loop node or conditional edges instead of wiring the last node back to the start.
4. Validate the workflow definition JSON (nodes/edges) after import or migration before running.

Example fix

// before
edges: [{source: "end", target: "start"}] // cycle, no in-degree-0 node
// after
edges: [] // start node has no incoming edges

boolean hasSource = graph.vertexSet().stream().anyMatch(n -> graph.incomingEdgesOf(n).isEmpty());
if (!hasSource) throw new IllegalStateException("workflow needs a start node with no incoming edges");

try {
    manager.execute(context);
} catch (BizException e) {
    if ("WORKFLOW_CONFIG_INVALID".equals(e.getCode())) { /* fix graph topology before running */ }
}

When it happens

Trigger: Saving/running a workflow whose edges form a cycle covering all nodes, or whose start node incorrectly has an incoming edge (e.g. an edge drawn into the Start node), leaving zero nodes with in-degree 0.

Common situations: Hand-edited or imported workflow JSON with a wrong edge list; connecting an end/loop node back to the start node creating a full cycle; a misconfigured loop workflow without an explicit start; migration bugs that reindex node ids so edges point at the wrong nodes.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• WORKFLOW_CONFIG_INVALID
• WORKFLOW_CONFIG_ILLEGAL
• oss ak or sk should be set.
• oss bucket should be set.
• AppNotFound

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/75e5699f9479b7dc. Report an issue: GitHub.