iflytek/astron-agent · error · ValueError

Start node ( ) not found.

Error message

Start node ({builder.start_node_id}) not found.

What it means

After building nodes, create_debug_node tries to return the node instance for builder.start_node_id from engine.engine_ctx.built_nodes. If the start node (nodes[0].id) is not in built_nodes, the engine build silently skipped it and the lookup fails, raising ValueError.

Solutions

1. Verify the first node's type is supported and gets built by build_nodes
2. Inspect build_nodes logs for skipped or failed node conversions
3. Reorder or fix the DSL so nodes[0] is a buildable node

Example fix

// before
engine_node = dsl_engine.create_debug_node(dsl, node_id, span)
// after
assert dsl.nodes[0].id, "first node has no id"
engine_node = dsl_engine.create_debug_node(dsl, node_id, span)

first = sparkflow_dsl.nodes[0]
assert first.id, "first node has no id"
node = engine.create_debug_node(sparkflow_dsl, first.id, span)

def start_node_built(dsl, builder) -> bool:
    return bool(dsl.nodes) and dsl.nodes[0].id in builder.built_nodes

try:
    node = engine.create_debug_node(dsl, node_id, span)
except ValueError as e:
    logger.error("start node missing after build: %s", e)
    raise HTTPException(422, str(e))

When it happens

Trigger: Calling create_debug_node where the first node in sparkflow_dsl.nodes was not materialized during build_nodes — e.g. its node type failed to resolve to a builder so it never entered built_nodes, while the empty-node check (1200) still passed.

Common situations: DSL containing only unsupported/unknown node types; nodes[0] being a special node skipped during build; partial engine builds after a silent build failure.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• WorkflowDSL must have at least one node.
• ENG_PROTOCOL_VALIDATE_ERROR
• ENG_PROTOCOL_VALIDATE_ERROR
• PROTOCOL_BUILD_ERROR
• UPDATE_BOT_FAILED

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

Appendix: source

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

        :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.

    Implements the Builder pattern to construct workflow engines step by step,
    including building chains, nodes, dependencies, and execution status.
    """

    chains: Chains

    def __init__(self, sparkflow_dsl: WorkflowDSL):
        self.sparkflow_dsl: WorkflowDSL = sparkflow_dsl
        self.built_nodes: Dict[str, SparkFlowEngineNode] = {}
        self.start_node_id: str = ""
        self.variable_pool = VariablePool(sparkflow_dsl.nodes)
        self.iteration_engine_nodes: Dict[str, str] = {}

View on GitHub (pinned to 5e758547a8)