What causes "Failed to build runner" in iflytek/astron-agent?

Inspect the logs/span for the underlying exception raised inside build_runner and fix that root cause

iflytek/astron-agent · critical · AgentInternalExc

Failed to build runner

Error message

Failed to build runner

What it means

Raised in run_runner when build_runner(sp) returns None or throws, wrapped as AgentInternalExc('Failed to build runner'). It signals that the agent runner could not be constructed for the given span/params, so the stream cannot start.

Solutions

Inspect the logs/span for the underlying exception raised inside build_runner and fix that root cause
Verify the agent's model and plugin configuration exists and is valid for the requesting space
Confirm required credentials (API keys, endpoints) for the configured model provider are present
Re-deploy/restart the agent service if a plugin or dependency failed to initialize

Defensive patterns

Strategy: try-catch

Try / catch

try:
    runner = await build_runner(sp)
except Exception as e:
    logger.exception("runner build failed")
    return error_response(500, "Failed to build runner", cause=str(e))

Prevention

Validate agent model/plugin configuration before invoking the run endpoint
Ensure model provider credentials are present in the environment
Add health checks that exercise build_runner on service startup

When it happens

Trigger: Calling the run/stream endpoint where build_runner returns None because the agent/plugin/model config is missing or invalid, or build_runner raises an internal exception that is converted into this generic failure.

Common situations: Model provider credentials not configured; plugin referenced by the agent is unavailable; invalid agent configuration saved in the console; dependency initialization failing at runtime.

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 iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/ec51f9ed071bdfa5. Report an issue: GitHub.

Appendix: source

Thrown at core/agent/api/v1/base_api.py:208

        self, node_trace_log: NodeTraceLog, meter: Meter, span: Span
    ) -> AsyncGenerator[str, None]:

        with span.start("RunRunner") as sp:
            chunk_logs: List[str] = []
            context = RunContext(
                error=AgentNormalExc(),
                error_log="",
                chunk_logs=chunk_logs,
                span=sp,
                node_trace_log=node_trace_log,
                meter=meter,
            )

            try:
                try:
                    runner = await self.build_runner(sp)
                    if runner is None:
                        raise AgentInternalExc("Failed to build runner")

                    runner_stream = runner.run(span=sp, node_trace_log=node_trace_log)
                    if inspect.isawaitable(runner_stream):
                        runner_stream = await runner_stream
                    async with aclosing(runner_stream):
                        async for chunk in runner_stream:
                            chunk.id = span.sid
                            processed_stream = self._process_chunk(chunk, chunk_logs)
                            async with aclosing(processed_stream):
                                async for processed_chunk in processed_stream:
                                    yield processed_chunk

                except BaseExc as exc:
                    context.error = exc
                    context.error_log = traceback.format_exc()
                except Exception as exc:  # pylint: disable=broad-exception-caught
                    context.error = AgentInternalExc(str(exc))
                    context.error_log = traceback.format_exc()

View on GitHub (pinned to 5e758547a8)