{"record":{"id":"eb1960b6967f1849","repo":"iflytek/astron-agent","slug":"spark-link-connection-error","errorCode":"SPARK_LINK_CONNECTION_ERROR","errorMessage":"Tool request failed, connection error","messagePattern":"Tool request failed, connection error","errorType":"error_code","errorClass":"CustomException","httpStatus":null,"severity":"critical","filePath":"core/workflow/engine/nodes/plugin_tool/link_client.py","lineNumber":292,"sourceCode":"                        self.run_url, json=run_link_payload\n                    ) as response:\n                        link_response = await response.json()\n                        # Log response timing and content\n                        await link_tool_span.add_info_events_async(\n                            {\n                                \"plugin_node_link_post_cost_time\": f\"{time.time() * 1000 - start_time}\"\n                            }\n                        )\n                        await link_tool_span.add_info_events_async(\n                            {\n                                \"link_response\": json.dumps(\n                                    link_response, ensure_ascii=False\n                                )\n                            }\n                        )\n            except requests.ConnectionError as e:\n                # Handle connection errors\n                raise CustomException(\n                    CodeEnum.SPARK_LINK_CONNECTION_ERROR,\n                    err_msg=\"Tool request failed, connection error\",\n                    cause_error=\"Tool request failed, connection error\",\n                ) from e\n            except Exception as e:\n                # Handle other exceptions\n                raise e\n\n            await link_tool_span.add_info_events_async(\n                {\"link_response\": json.dumps(link_response, ensure_ascii=False)}\n            )\n\n            # Process response and handle errors\n            code = link_response[\"header\"][\"code\"]\n            message = link_response[\"header\"][\"message\"]\n\n            if code != 0:\n                # Handle tool execution errors","sourceCodeStart":274,"sourceCodeEnd":310,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/workflow/engine/nodes/plugin_tool/link_client.py#L274-L310","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the Link service is running and reachable (curl the configured URL from the workflow service host)","Check and correct the Link base URL/port in the node or environment configuration","Inspect network policies, DNS, and proxy settings; then re-run the workflow"],"exampleFix":"// before (client configured with wrong host)\nclient = LinkClient(base_url=\"http://link-svc:9999\")\n// after\nclient = LinkClient(base_url=\"http://link-svc:8080\")  # correct port after checking service","handlingStrategy":"try-catch","validationCode":"import requests\ntry:\n    requests.get(link_base_url, timeout=5)\nexcept requests.ConnectionError:\n    ...  # surface config/network problem before running the tool","typeGuard":null,"tryCatchPattern":"try:\n    result = link_client.run(...)\nexcept CustomException as e:\n    if e.code == CodeEnum.SPARK_LINK_CONNECTION_ERROR:\n        alert(\"Link service unreachable; check URL and service health\")","preventionTips":["Health-check the Link service URL before deployments","Pin correct host/port in environment config and verify with curl","Add retries with backoff for transient network failures"],"tags":["network","http","connection"],"backgroundTag":"connection-refused","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}