{"record":{"id":"9a80aeddd555dcda","repo":"datawhalechina/hello-agents","slug":"e-reason","errorCode":null,"errorMessage":"网络连接失败: {e.reason}","messagePattern":"网络连接失败: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"Co-creation-projects/chengH425-PaperAssistant/src/literature_tool.py","lineNumber":224,"sourceCode":"                    if attempt < max_retries - 1:\n                        time.sleep(wait)\n                        continue\n                    raise RuntimeError(\n                        \"API 请求频率已达上限（429 Too Many Requests）。\\n\"\n                        \"Semantic Scholar 免费额度为 100 次/5 分钟。\\n\"\n                        \"请稍等 1-5 分钟后重试，或申请免费 API Key：\\n\"\n                        \"https://www.semanticscholar.org/product/api\\n\"\n                        \"获取后在 .env 中设置 SEMANTIC_SCHOLAR_API_KEY\"\n                    ) from e\n                raise RuntimeError(\n                    f\"Semantic Scholar API 返回 HTTP {e.code}: {e.reason}\"\n                ) from e\n            except urllib.error.URLError as e:\n                last_error = e\n                if attempt < max_retries - 1:\n                    time.sleep(2 ** (attempt + 1))\n                    continue\n                raise RuntimeError(f\"网络连接失败: {str(e.reason)}\") from e\n\n        raise RuntimeError(f\"请求失败（已重试 {max_retries} 次）: {last_error}\")\n\n    def run(self, parameters: Dict[str, Any]) -> ToolResponse:\n        keyword = parameters.get(\"keyword\", \"\")\n        author = parameters.get(\"author\", \"\")\n        field = parameters.get(\"field\", \"\")\n\n        if not keyword and not author:\n            return ToolResponse.error(\n                code=\"INVALID_PARAM\",\n                message=\"请至少提供关键词（keyword）或作者（author）\"\n            )\n\n        url = self._build_url(parameters)\n        api_key = os.getenv(\"SEMANTIC_SCHOLAR_API_KEY\", \"\")\n\n        try:","sourceCodeStart":206,"sourceCodeEnd":242,"githubUrl":"https://github.com/datawhalechina/hello-agents/blob/606a07d341a47be773fab7f4b71177f53f96b2c3/Co-creation-projects/chengH425-PaperAssistant/src/literature_tool.py#L206-L242","documentation":"RuntimeError raised when a `urllib.error.URLError` (DNS failure, connection refused, TLS error, timeout) persists after all retry attempts in the Semantic Scholar client. The message embeds `e.reason`, e.g. 'network connection failed: [Errno -2] Name or service not known'. It indicates the request never got an HTTP response at all.","triggerScenarios":"No internet or a proxy/firewall blocks api.semanticscholar.org; DNS resolution fails in the runtime environment; the process runs in an offline container or a network-restricted CI sandbox; TLS interception rejects the certificate.","commonSituations":"Local dev behind a corporate proxy without HTTPS_PROXY set, Docker containers without DNS configured, air-gapped environments, or transient ISP outages that outlast the short 2s/4s/8s backoff.","solutions":["Verify connectivity from the same environment: `curl -I https://api.semanticscholar.org/graph/v1/paper/search?query=test`.","If behind a proxy, set HTTP_PROXY/HTTPS_PROXY (urllib honors them); for custom CA bundles set SSL_CERT_FILE.","Retry after the network issue clears — the client already does 3 attempts with backoff.","In containers, check DNS (`docker run --rm busybox nslookup api.semanticscholar.org`)."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"import socket, urllib.request\n\ndef endpoint_reachable(url: str = \"https://api.semanticscholar.org\", timeout: float = 5) -> bool:\n    try:\n        urllib.request.urlopen(url, timeout=timeout)\n        return True\n    except urllib.error.HTTPError:\n        return True   # got an HTTP response => network is fine\n    except (urllib.error.URLError, socket.timeout, OSError):\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    data = _request(url)\nexcept RuntimeError as e:\n    msg = str(e)\n    if \"网络连接失败\" in msg or \"Name or service not known\" in msg:\n        check_proxy_and_dns(); time.sleep(60); data = _request(url)\n    else:\n        raise","preventionTips":["In proxied environments set HTTPS_PROXY/HTTP_PROXY before starting the app.","Add a connectivity preflight before batch literature jobs.","In containers, verify DNS resolves api.semanticscholar.org."],"tags":["network","dns","proxy","urllib","semantic-scholar","python"],"backgroundTag":null,"analyzedSha":"606a07d341a47be773fab7f4b71177f53f96b2c3","analyzedAt":"2026-08-14T22:57:27.446Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}