iflytek/astron-agent · critical · CustomException

SPARK_LINK_CONNECTION_ERROR

SPARK_LINK_CONNECTION_ERROR

Error message

Tool request failed, connection error

What it means

The Spark Link plugin-tool client wraps requests.ConnectionError raised while calling the remote Link tool HTTP endpoint and rethrows it as SPARK_LINK_CONNECTION_ERROR. It means the TCP/HTTP connection to the Link service could not be established or was dropped mid-request, so the tool call never produced a response.

Solutions

  1. Verify the Link service is running and reachable (curl the configured URL from the workflow service host)
  2. Check and correct the Link base URL/port in the node or environment configuration
  3. Inspect network policies, DNS, and proxy settings; then re-run the workflow

Example fix

// before (client configured with wrong host)
client = LinkClient(base_url="http://link-svc:9999")
// after
client = LinkClient(base_url="http://link-svc:8080")  # correct port after checking service
Defensive patterns

Strategy: try-catch

Validate before calling

import requests
try:
    requests.get(link_base_url, timeout=5)
except requests.ConnectionError:
    ...  # surface config/network problem before running the tool

Try / catch

try:
    result = link_client.run(...)
except CustomException as e:
    if e.code == CodeEnum.SPARK_LINK_CONNECTION_ERROR:
        alert("Link service unreachable; check URL and service health")

Prevention

When it happens

Trigger: Calling the Link tool via run() when the Link service is down, the configured get_url/post_url host is wrong or unreachable, DNS fails, or a timeout/network partition kills the connection.

Common situations: Link microservice not deployed or crashed in the environment, wrong service URL/port in configuration, Kubernetes service name mismatch, firewall or network policy blocking egress, or TLS/proxy issues.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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

Appendix: source

Thrown at core/workflow/engine/nodes/plugin_tool/link_client.py:292

                        self.run_url, json=run_link_payload
                    ) as response:
                        link_response = await response.json()
                        # Log response timing and content
                        await link_tool_span.add_info_events_async(
                            {
                                "plugin_node_link_post_cost_time": f"{time.time() * 1000 - start_time}"
                            }
                        )
                        await link_tool_span.add_info_events_async(
                            {
                                "link_response": json.dumps(
                                    link_response, ensure_ascii=False
                                )
                            }
                        )
            except requests.ConnectionError as e:
                # Handle connection errors
                raise CustomException(
                    CodeEnum.SPARK_LINK_CONNECTION_ERROR,
                    err_msg="Tool request failed, connection error",
                    cause_error="Tool request failed, connection error",
                ) from e
            except Exception as e:
                # Handle other exceptions
                raise e

            await link_tool_span.add_info_events_async(
                {"link_response": json.dumps(link_response, ensure_ascii=False)}
            )

            # Process response and handle errors
            code = link_response["header"]["code"]
            message = link_response["header"]["message"]

            if code != 0:
                # Handle tool execution errors

View on GitHub (pinned to 5e758547a8)