datawhalechina/hello-agents · error · RuntimeError

网络连接失败: {e.reason}

Error message

网络连接失败: {e.reason}

What it means

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.

Source

Thrown at Co-creation-projects/chengH425-PaperAssistant/src/literature_tool.py:224

                    if attempt < max_retries - 1:
                        time.sleep(wait)
                        continue
                    raise RuntimeError(
                        "API 请求频率已达上限（429 Too Many Requests）。\n"
                        "Semantic Scholar 免费额度为 100 次/5 分钟。\n"
                        "请稍等 1-5 分钟后重试，或申请免费 API Key：\n"
                        "https://www.semanticscholar.org/product/api\n"
                        "获取后在 .env 中设置 SEMANTIC_SCHOLAR_API_KEY"
                    ) from e
                raise RuntimeError(
                    f"Semantic Scholar API 返回 HTTP {e.code}: {e.reason}"
                ) from e
            except urllib.error.URLError as e:
                last_error = e
                if attempt < max_retries - 1:
                    time.sleep(2 ** (attempt + 1))
                    continue
                raise RuntimeError(f"网络连接失败: {str(e.reason)}") from e

        raise RuntimeError(f"请求失败（已重试 {max_retries} 次）: {last_error}")

    def run(self, parameters: Dict[str, Any]) -> ToolResponse:
        keyword = parameters.get("keyword", "")
        author = parameters.get("author", "")
        field = parameters.get("field", "")

        if not keyword and not author:
            return ToolResponse.error(
                code="INVALID_PARAM",
                message="请至少提供关键词（keyword）或作者（author）"
            )

        url = self._build_url(parameters)
        api_key = os.getenv("SEMANTIC_SCHOLAR_API_KEY", "")

        try:

View on GitHub (pinned to 606a07d341)

Solutions

1. Verify connectivity from the same environment: `curl -I https://api.semanticscholar.org/graph/v1/paper/search?query=test`.
2. If behind a proxy, set HTTP_PROXY/HTTPS_PROXY (urllib honors them); for custom CA bundles set SSL_CERT_FILE.
3. Retry after the network issue clears — the client already does 3 attempts with backoff.
4. In containers, check DNS (`docker run --rm busybox nslookup api.semanticscholar.org`).

import socket, urllib.request

def endpoint_reachable(url: str = "https://api.semanticscholar.org", timeout: float = 5) -> bool:
    try:
        urllib.request.urlopen(url, timeout=timeout)
        return True
    except urllib.error.HTTPError:
        return True   # got an HTTP response => network is fine
    except (urllib.error.URLError, socket.timeout, OSError):
        return False

try:
    data = _request(url)
except RuntimeError as e:
    msg = str(e)
    if "网络连接失败" in msg or "Name or service not known" in msg:
        check_proxy_and_dns(); time.sleep(60); data = _request(url)
    else:
        raise

When it happens

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

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

Related errors

• 请求失败（已重试 {max_retries} 次）: {last_error}
• TMDB 网络错误: {e}
• API 请求频率已达上限（429 Too Many Requests）。\nSemantic Scholar 免费额度为
• Semantic Scholar API 返回 HTTP {e.code}: {e.reason}
• 工具 '{tool_name}' 执行超时

AI-assisted analysis of datawhalechina/hello-agents@606a07d341 (2026-08-14). Data as JSON: /api/errors/9a80aeddd555dcda. Report an issue: GitHub.