HKUDS/DeepTutor · error · EmbeddingProviderError

OpenAI SDK connection error

Error message

OpenAI SDK connection error: {exc}

What it means

The OpenAI SDK raised APIConnectionError before/while reaching the server — network-level failure such as DNS resolution failure, connection refused, TLS handshake error, or no route to host. No HTTP response exists, so the wrapper carries only model and URL.

Solutions

1. Verify base_url host resolves and the service is up: curl the embeddings endpoint
2. If behind a proxy, set HTTPS_PROXY/HTTP_PROXY so the SDK can egress
3. Fix hostname/port typos in the embedding binding config
4. For transient network blips, retry the embed() call with backoff

Example fix

# before
base_url = "https://api.openai.com/v1/embbedings"  # typo'd host path -> connection/DNS issues on proxies
# after
base_url = "https://api.openai.com/v1"

import socket

def host_reachable(base_url: str) -> bool:
    from urllib.parse import urlparse
    u = urlparse(base_url)
    try:
        socket.getaddrinfo(u.hostname, u.port or 443)
        return True
    except socket.gaierror:
        return False

null

try:
    resp = await adapter.embed(req)
except EmbeddingProviderError as e:
    if "connection error" in str(e).lower():
        for delay in (1, 2, 4):
            await asyncio.sleep(delay)
            try:
                resp = await adapter.embed(req); break
            except EmbeddingProviderError:
                continue
        else:
            raise NetworkError(str(e)) from e
    raise

When it happens

Trigger: DNS for the base_url host fails; endpoint/port unreachable (service down, firewall, VPN); TLS certificate mismatch; local proxy required but not set. The SDK's built-in retries (max_retries=2) were also exhausted.

Common situations: Self-hosted gateway down; typo in base_url hostname; corporate proxy blocking api.openai.com; IPv6/mDNS issues; container without network egress.

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

• graphrag_embedding_probe_failed
• Network error connecting to
• OpenAI SDK request failed
• Cannot parse embeddings from response JSON. Top-level keys=
• Channel onboarding provider request failed

AI-assisted analysis of HKUDS/DeepTutor@3e82f13042 (2026-08-27). Data as JSON: /api/errors/748ee495259bca4f. Report an issue: GitHub.

Appendix: source

Thrown at deeptutor/services/embedding/adapters/openai_sdk.py:97

        client = self._build_client()
        try:
            response = await client.embeddings.create(**kwargs)
        except APIStatusError as exc:
            try:
                body = exc.response.text
            except Exception:
                body = str(exc)
            raise EmbeddingProviderError(
                f"OpenAI SDK request failed: {exc}",
                status=getattr(exc, "status_code", None),
                body=body,
                model=model,
                url=self.base_url,
                provider="openai_sdk",
            ) from exc
        except APIConnectionError as exc:
            raise EmbeddingProviderError(
                f"OpenAI SDK connection error: {exc}",
                model=model,
                url=self.base_url,
                provider="openai_sdk",
            ) from exc
        except APIError as exc:
            raise EmbeddingProviderError(
                f"OpenAI SDK API error: {exc}",
                model=model,
                url=self.base_url,
                provider="openai_sdk",
            ) from exc
        finally:
            try:
                await client.close()
            except Exception:
                pass

View on GitHub (pinned to 3e82f13042)