iflytek/astron-agent · error · ValueError

WorkflowDSL must have at least one node.

Error message

WorkflowDSL must have at least one node.

What it means

create_debug_node builds a debug node instance from a WorkflowDSL but first requires the DSL to contain at least one node. If sparkflow_dsl.nodes is an empty list, the engine cannot determine a start node, so it raises ValueError. This guards against building an engine with no executable graph.

Solutions

1. Add at least one node to the workflow DSL before calling create_debug_node
2. Check len(dsl.nodes) > 0 in the caller before invoking
3. Fix the DSL serialization/deserialization path if nodes were dropped

Example fix

// before
engine_node = dsl_engine.create_debug_node(dsl, node_id, span)  # dsl.nodes == []
// after
if not dsl.nodes:
    raise HTTPException(400, "Workflow has no nodes to debug")
engine_node = dsl_engine.create_debug_node(dsl, node_id, span)

if not sparkflow_dsl.nodes:
    raise ValueError("Cannot create debug node: DSL has no nodes")
node = engine.create_debug_node(sparkflow_dsl, node_id, span)

def has_nodes(dsl) -> bool:
    return bool(getattr(dsl, "nodes", None))

try:
    node = engine.create_debug_node(dsl, node_id, span)
except ValueError as e:
    logger.error("debug node creation failed: %s", e)
    return None

When it happens

Trigger: Calling create_debug_node with a WorkflowDSL whose nodes list is empty — e.g. a DSL constructed programmatically without nodes, or a deserialized DSL from an empty/deleted workflow.

Common situations: Debugging a freshly created workflow before any nodes were added on the canvas; frontend sending an empty nodes array in a debug request; DSL export/import losing nodes.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• ENG_PROTOCOL_VALIDATE_ERROR
• WORKFLOW_VERSION_PUBLISH_FAILED
• 8008
• 8008
• WORKFLOW_PROTOCOL_NODE_INFO_CANNOT_EMPTY

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/e78c4a879ab2e618. Report an issue: GitHub.

Appendix: source

Thrown at core/workflow/engine/dsl_engine.py:1987

            sub_dsl = sparkflow_dsl.extract_loop_sub_dsl(loop_node_id)
        return WorkflowEngineFactory.create_engine(sub_dsl, span)

    @staticmethod
    def create_debug_node(
        sparkflow_dsl: WorkflowDSL,
        span: Span,
    ) -> BaseNode:
        """
        Create a debug node.

        :param sparkflow_dsl: Workflow DSL definition
        :param span: Tracing span for observability
        :return: BaseNode instance for debugging
        """
        with span.start() as span_context:
            builder = WorkflowEngineBuilder(sparkflow_dsl).build_nodes(span_context)
            if len(sparkflow_dsl.nodes) == 0:
                raise ValueError("WorkflowDSL must have at least one node.")
            builder.start_node_id = sparkflow_dsl.nodes[0].id
            builder.chains = Chains(workflow_schema=sparkflow_dsl)
            engine = builder.build()
            if (
                engine.engine_ctx
                and builder.start_node_id in engine.engine_ctx.built_nodes
            ):
                return engine.engine_ctx.built_nodes[
                    builder.start_node_id
                ].node_instance
            else:
                raise ValueError(f"Start node ({builder.start_node_id}) not found.")


class WorkflowEngineBuilder:
    """
    Builder for constructing workflow engines.

View on GitHub (pinned to 5e758547a8)