Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

patch: explain provider model discovery failures (#2090)

Ali Khokhara226fa2635cb
diff --git a/e2e/test_admin_apply.py b/e2e/test_admin_apply.py
index 5e968937..173c9bc1 100644
--- a/e2e/test_admin_apply.py
+++ b/e2e/test_admin_apply.py
@@ -4,6 +4,32 @@ import pytest
from playwright.sync_api import Page, Route, expect
from e2e.provider_support import api_key_input, close_provider, open_provider
+from free_claude_code.providers.credential_validation import check_credentials
+
+
+ "provider_id,key,owners",
+ [
+ ("nvidia_nim", "NVIDIA_NIM_API_KEY", "NVIDIA NIM"),
+ ("opencode_go", "OPENCODE_API_KEY", "OpenCode Zen and OpenCode Go"),
+ ("zai_api", "ZAI_API_KEY", "Z.ai Coding Plan and Z.ai API"),
+ ],
+)
+def test_saved_unverified_notice_names_the_credential_owners(
+ page, admin_base_url, monkeypatch, provider_id, key, owners
+):
+ monkeypatch.setattr(
+ "free_claude_code.runtime.application.check_credentials", check_credentials
+ )
+ page.goto(f"{admin_base_url}/admin")
+ dialog = open_provider(page, provider_id)
+ api_key_input(page, key).fill("e2e-saved-unverified")
+ dialog.get_by_role("button", name="Save", exact=True).click()
+ message = f"Key saved. Automatic verification is unavailable for {owners}."
+ expect(dialog).to_be_visible()
+ expect(dialog.get_by_text(message, exact=True)).to_be_visible()
+ expect(page.locator("#messageArea")).to_contain_text(message)
+ expect(page.locator("#dirtyState")).to_have_text("No changes")
def test_apply_is_the_only_config_action_and_retains_invalid_edits(
@@ -147,7 +173,9 @@ def test_unverified_warning_survives_apply(
open_provider(page, "nvidia_nim")
api_key_input(page, "NVIDIA_NIM_API_KEY").fill("new-key")
page.get_by_role("button", name="Save", exact=True).click()
- expect(page.locator("#messageArea")).to_contain_text("Verification unavailable.")
+ expect(page.locator("#messageArea")).to_contain_text(
+ "Key saved. Verification unavailable."
+ )
expect(page.locator("#dirtyState")).to_have_text("No changes")
expect(page.locator('[data-provider="nvidia_nim"]')).to_be_enabled()
expect(page.locator("#applyButton")).to_have_text("Apply")
diff --git a/e2e/test_admin_providers.py b/e2e/test_admin_providers.py
index f383ac65..e8554b14 100644
--- a/e2e/test_admin_providers.py
+++ b/e2e/test_admin_providers.py
@@ -263,8 +263,7 @@ def test_provider_check_failure_is_separate_and_never_exposes_exception_text(
result = card.locator(".provider-check-result")
expect(result).to_have_text(
- "Unavailable: Could not refresh this provider's models. "
- "Verify its configuration and access."
+ "Unavailable: Could not load models. Check the provider's settings and retry."
)
expect(card.get_by_role("button", name="Edit", exact=True)).to_have_class(
"secondary-button"
diff --git a/e2e/test_progressive_startup.py b/e2e/test_progressive_startup.py
index e65552c1..886a8bc9 100644
--- a/e2e/test_progressive_startup.py
+++ b/e2e/test_progressive_startup.py
@@ -1,9 +1,47 @@
+import pytest
from playwright.sync_api import expect
from e2e.provider_support import api_key_input, close_provider, open_provider
from e2e.test_code_sessions import create_session
+ "admin_base_url", [{"NVIDIA_NIM_API_KEY": "e2e-nim-key"}], indirect=True
+)
+def test_discovery_error_is_visible_in_provider_card_and_refresh_result(
+ page, admin_base_url
+):
+ proxy_message = "The network proxy rejected or failed the connection. Check your proxy settings."
+ http_message = "The model-list request returned HTTP 403."
+
+ def status(route):
+ data = route.fetch().json()
+ data["startup"]["providers"]["nvidia_nim"] = "failed"
+ data["startup"]["provider_errors"] = {"nvidia_nim": proxy_message}
+ route.fulfill(json=data)
+
+ page.route("**/admin/api/status", status)
+ page.route(
+ "**/admin/api/providers/nvidia_nim/test",
+ lambda route: route.fulfill(
+ json={"provider_id": "nvidia_nim", "ok": False, "message": http_message}
+ ),
+ )
+ page.goto(f"{admin_base_url}/admin")
+ card = page.locator('[data-provider-check-result="nvidia_nim"]')
+ expect(card).to_have_text(proxy_message)
+ dialog = open_provider(page, "nvidia_nim")
+ expect(dialog.locator("#providerDialogCheck")).to_have_text(proxy_message)
+ expect(
+ dialog.get_by_text(
+ "Optional network proxy. Leave blank unless you use one", exact=True
+ )
+ ).to_be_visible()
+ dialog.get_by_role("button", name="Refresh models", exact=True).click()
+ expect(dialog.locator("#providerDialogCheck")).to_contain_text(http_message)
+ expect(card).to_contain_text(http_message)
+
+
def test_provider_and_messaging_progress_preserve_settings(page, admin_base_url):
starting = True
provider_tests = []
diff --git a/src/free_claude_code/api/admin_static/admin.js b/src/free_claude_code/api/admin_static/admin.js
index 1e08faf8..72c670b1 100644
--- a/src/free_claude_code/api/admin_static/admin.js
+++ b/src/free_claude_code/api/admin_static/admin.js
@@ -781,7 +781,7 @@ function providerCheckResult(providerId) {
const discovery = state.startup?.startup?.providers?.[providerId];
if (discovery === "starting") return { status: "checking", message: "Checking models…" };
if (discovery === "failed") {
- return { status: "error", message: "Could not load models. Check the provider's settings and retry." };
+ return { status: "error", message: state.startup.startup.provider_errors?.[providerId] || "Could not load models. Check the provider's settings and retry." };
}
if (discovery === "ready") {
return { status: "ok", message: modelCountMessage(state.startup.cached_models[providerId]?.length || 0) };
@@ -1544,7 +1544,7 @@ async function showRestartNotice() {
async function restoreSavedProvider(providerId, checks) {
if (!connectedAccountDescriptor(providerId)) return;
await openProviderDialog(providerId);
- showCredentialErrors(checks);
+ showCredentialErrors(checks.map((check) => ({ ...check, message: `Key saved. ${check.message}` })));
byId("providerMessage").textContent = "Saved. Some keys could not be verified.";
byId("providerMessage").className = "message-area warn";
}
@@ -1598,7 +1598,7 @@ async function apply(providerId = null, customAction = null) {
applied = true;
const warningChecks = checks.filter((check) => check.status === "unverified");
const warnings = warningChecks.map((check) =>
- `${state.fields.get(check.key)?.label || "API keys"}, Key ${check.index + 1}: ${check.message}`
+ `${state.fields.get(check.key)?.label || "API keys"}, Key ${check.index + 1}: Key saved. ${check.message}`
);
const savedProviderId = warnings.length && providerId && mutation?.action !== "delete" ? result.custom_provider_id || providerId : null;
if (providerId && !savedProviderId) byId("providerDialog").close();
diff --git a/src/free_claude_code/application/model_metadata.py b/src/free_claude_code/application/model_metadata.py
index 08ac3590..f642cb62 100644
--- a/src/free_claude_code/application/model_metadata.py
+++ b/src/free_claude_code/application/model_metadata.py
@@ -1,6 +1,6 @@
"""Application-owned model metadata."""
-from dataclasses import dataclass
+from dataclasses import dataclass, field
from free_claude_code.core.model_capabilities import ModelInputModality
from free_claude_code.core.reasoning import ReasoningCapability
@@ -24,3 +24,4 @@ class ProviderModelRefreshResult:
refreshed_provider_ids: tuple[str, ...] = ()
failed_provider_ids: tuple[str, ...] = ()
+ failure_messages: dict[str, str] = field(default_factory=dict)
diff --git a/src/free_claude_code/config/admin/provider_manifest.py b/src/free_claude_code/config/admin/provider_manifest.py
index 41fceea7..3fe53841 100644
--- a/src/free_claude_code/config/admin/provider_manifest.py
+++ b/src/free_claude_code/config/admin/provider_manifest.py
@@ -27,7 +27,8 @@ _PROVIDER_FIELD_OVERRIDES: dict[str, ProviderFieldOverride] = {
},
"OPENAI_PROXY": {
"description": (
- "Optional proxy used for OpenAI sign-in and ChatGPT Codex requests. "
+ "Optional network proxy. Leave blank unless you use one. "
+ "Used for OpenAI sign-in and ChatGPT Codex requests. "
"Changing it restarts FCC."
),
"restart_required": True,
@@ -474,6 +475,7 @@ def _proxy_field_specs() -> tuple[ConfigFieldSpec, ...]:
ConfigFieldSpec(
key=_settings_env_key(descriptor.proxy_attr),
label=f"{descriptor.display_name} Proxy",
+ description="Optional network proxy. Leave blank unless you use one",
section_id="providers",
field_type="secret",
settings_attr=descriptor.proxy_attr,
diff --git a/src/free_claude_code/providers/credential_validation.py b/src/free_claude_code/providers/credential_validation.py
index cc332b0e..d1d439c4 100644
--- a/src/free_claude_code/providers/credential_validation.py
+++ b/src/free_claude_code/providers/credential_validation.py
@@ -320,7 +320,16 @@ async def check_credentials(
CredentialCheck(
submission.key,
CredentialStatus.UNVERIFIED,
- "Automatic key verification is unavailable for this provider.",
+ "Automatic verification is unavailable for "
+ + (
+ " and ".join(
+ descriptor.display_name
+ for descriptor in PROVIDER_CATALOG.values()
+ if descriptor.credential_env == submission.key
+ )
+ or "this provider"
+ )
+ + ".",
index,
submission.provider_id,
)
diff --git a/src/free_claude_code/providers/runtime/discovery.py b/src/free_claude_code/providers/runtime/discovery.py
index 69c2b8e9..2833cbb4 100644
--- a/src/free_claude_code/providers/runtime/discovery.py
+++ b/src/free_claude_code/providers/runtime/discovery.py
@@ -1,28 +1,106 @@
"""Provider model-list discovery and background refresh."""
+import re
+import socket
+import ssl
+
import httpx
+import httpx2
from free_claude_code.application.errors import ApplicationUnavailableError
from free_claude_code.config.model_refs import configured_chat_model_refs
from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
from free_claude_code.config.settings import Settings
-from free_claude_code.core.failures import ExecutionFailure
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.providers.model_listing import ModelListResponseError
from .config import has_provider_configuration
+_FAILURE_MESSAGES = {
+ "proxy": "The network proxy rejected or failed the connection. Check your proxy settings.",
+ "dns": "DNS lookup failed. Check your network and provider or proxy address.",
+ "certificate": "TLS certificate verification failed. Check your network's certificate configuration.",
+ "tls": "The TLS connection failed. Check your network and proxy settings.",
+ "timeout": "The model-list request timed out. Check connectivity and retry.",
+ "connection": "Could not connect to the provider. Check your network and proxy settings.",
+ "response": "The provider returned an invalid model list.",
+ "unavailable": "The provider is unavailable. Check its configuration and access.",
+ "unknown": "Could not load models. Check the provider's settings and retry.",
+}
+
+
+def safe_discovery_failure_message(value: object) -> str:
+ """Allow only classifier output into shareable diagnostics."""
+ if isinstance(value, str) and (
+ value in _FAILURE_MESSAGES.values()
+ or re.fullmatch(r"The model-list request returned HTTP [1-5][0-9]{2}\.", value)
+ ):
+ return value
+ return _FAILURE_MESSAGES["unknown"]
+
+
+def _provider_query_failure_reason(exc: BaseException) -> str:
+ """Classify the transport cause without copying upstream text or URLs."""
+ import openai
+
+ from free_claude_code.providers.failure_policy import ProviderRecoveryExhausted
-def _provider_query_failure_reason(exc: BaseException, settings: Settings) -> str:
- """Return a concise model-list query failure reason for user-facing logs."""
- if isinstance(exc, ModelListResponseError):
- return f"malformed model-list response: {exc.message}"
- if isinstance(exc, httpx.HTTPStatusError):
- return f"query failure: HTTP {exc.response.status_code}"
- if isinstance(exc, ApplicationUnavailableError):
- return f"query failure: {exc.message}"
- if isinstance(exc, ExecutionFailure) and settings.log_api_error_tracebacks:
- return f"query failure: {exc.message}"
- return f"query failure: {type(exc).__name__}"
+ chain: list[BaseException] = []
+ seen: set[int] = set()
+ current: BaseException | None = exc
+ while current is not None and id(current) not in seen:
+ seen.add(id(current))
+ chain.append(current)
+ if isinstance(current, ProviderRecoveryExhausted):
+ current = current.last_error
+ else:
+ # HTTPCore hides transport context with `raise exc from None`.
+ # It still carries the DNS/TLS cause needed for this classification.
+ current = current.__cause__ or current.__context__
+ # The SDK often wraps a more useful transport or OS error.
+ for error in reversed(chain):
+ if isinstance(error, (httpx.ProxyError, httpx2.ProxyError)):
+ return _FAILURE_MESSAGES["proxy"]
+ if isinstance(error, socket.gaierror):
+ return _FAILURE_MESSAGES["dns"]
+ if isinstance(error, ssl.SSLCertVerificationError):
+ return _FAILURE_MESSAGES["certificate"]
+ if isinstance(error, ssl.SSLError):
+ return _FAILURE_MESSAGES["tls"]
+ if isinstance(
+ error,
+ (
+ TimeoutError,
+ httpx.TimeoutException,
+ httpx2.TimeoutException,
+ openai.APITimeoutError,
+ ),
+ ):
+ return _FAILURE_MESSAGES["timeout"]
+ if isinstance(
+ error,
+ (httpx.HTTPStatusError, httpx2.HTTPStatusError, openai.APIStatusError),
+ ):
+ return safe_discovery_failure_message(
+ f"The model-list request returned HTTP {error.response.status_code}."
+ )
+ if isinstance(error, ModelListResponseError):
+ return _FAILURE_MESSAGES["response"]
+ if isinstance(
+ error,
+ (
+ ConnectionError,
+ httpx.NetworkError,
+ httpx2.NetworkError,
+ openai.APIConnectionError,
+ ),
+ ):
+ return _FAILURE_MESSAGES["connection"]
+ if isinstance(error, ExecutionFailure) and error.kind is FailureKind.TIMEOUT:
+ return _FAILURE_MESSAGES["timeout"]
+ if isinstance(error, (ApplicationUnavailableError, ExecutionFailure)):
+ return _FAILURE_MESSAGES["unavailable"]
+ return _FAILURE_MESSAGES["unknown"]
def referenced_provider_ids(settings: Settings) -> tuple[str, ...]:
diff --git a/src/free_claude_code/runtime/application.py b/src/free_claude_code/runtime/application.py
index a3efcda4..6c422620 100644
--- a/src/free_claude_code/runtime/application.py
+++ b/src/free_claude_code/runtime/application.py
@@ -486,7 +486,9 @@ class ApplicationRuntime:
return {
"provider_id": provider_id,
"ok": False,
- "message": _PROVIDER_CHECK_FAILURE_MESSAGE,
+ "message": result.failure_messages.get(
+ provider_id, _PROVIDER_CHECK_FAILURE_MESSAGE
+ ),
}
return {
"provider_id": provider_id,
diff --git a/src/free_claude_code/runtime/diagnostics.py b/src/free_claude_code/runtime/diagnostics.py
index ca119acc..7ffc2311 100644
--- a/src/free_claude_code/runtime/diagnostics.py
+++ b/src/free_claude_code/runtime/diagnostics.py
@@ -9,6 +9,8 @@ import subprocess
from typing import Any
from urllib.parse import urlsplit
+import httpx
+
from free_claude_code.config.loader import ManagedConfigStore
from free_claude_code.config.paths import (
claude_desktop_disconnect_path,
@@ -28,7 +30,10 @@ from free_claude_code.harnesses import (
from free_claude_code.providers.github_copilot.auth import CopilotAuthManager
from free_claude_code.providers.openai_codex.auth import saved_connection_state
from free_claude_code.providers.runtime.config import has_provider_configuration
-from free_claude_code.providers.runtime.discovery import referenced_provider_ids
+from free_claude_code.providers.runtime.discovery import (
+ referenced_provider_ids,
+ safe_discovery_failure_message,
+)
RUNTIME_FIELDS = (
"host",
@@ -293,6 +298,46 @@ def harness_report() -> dict[str, Any]:
return result
+def model_discovery_report(settings: Settings) -> dict[str, Any]:
+ """Read a safe snapshot from an existing local server without refreshing it."""
+ unavailable = {"status": "unavailable", "source": "running_server"}
+ try:
+ url = local_proxy_root_url(settings)
+ if urlsplit(url).hostname not in {"127.0.0.1", "localhost", "::1"}:
+ return unavailable
+ response = httpx.get(
+ f"{url}/admin/api/status",
+ timeout=2.0,
+ trust_env=False,
+ follow_redirects=False,
+ )
+ response.raise_for_status()
+ payload = response.json()
+ except httpx.HTTPError, httpx.InvalidURL, ValueError:
+ return unavailable
+ if not isinstance(payload, dict) or payload.get("status") != "running":
+ return unavailable
+ startup = payload.get("startup")
+ if not isinstance(startup, dict):
+ return unavailable
+ states, errors = startup.get("providers"), startup.get("provider_errors")
+ if not isinstance(states, dict) or not isinstance(errors, dict):
+ return unavailable
+ providers = {}
+ for provider_id, state in states.items():
+ if provider_id not in PROVIDER_CATALOG and not re.fullmatch(
+ r"custom_[a-f0-9]{32}", provider_id
+ ):
+ continue
+ if state not in ("starting", "ready", "failed"):
+ continue
+ row = {"state": state}
+ if state == "failed":
+ row["message"] = safe_discovery_failure_message(errors.get(provider_id))
+ providers[provider_id] = row
+ return {"status": "available", "source": "running_server", "providers": providers}
+
+
def collect_report() -> dict[str, Any]:
report = {
"version": package_version(),
@@ -314,6 +359,7 @@ def collect_report() -> dict[str, Any]:
"web_tools": None,
"integrations": None,
"harnesses": {},
+ "model_discovery": {"status": "unavailable", "source": "running_server"},
"errors": [],
}
store = ManagedConfigStore()
@@ -334,6 +380,7 @@ def collect_report() -> dict[str, Any]:
copilot if copilot in {"connected", "disconnected"} else "unavailable"
)
report.update(settings_report(settings, accounts))
+ report["model_discovery"] = model_discovery_report(settings)
report["integrations"] = integration_report(settings)
for name, state in accounts.items():
if state not in {"connected", "disconnected"}:
diff --git a/src/free_claude_code/runtime/provider_manager.py b/src/free_claude_code/runtime/provider_manager.py
index bdfe8de8..0ac830fd 100644
--- a/src/free_claude_code/runtime/provider_manager.py
+++ b/src/free_claude_code/runtime/provider_manager.py
@@ -292,12 +292,16 @@ class ProviderRuntimeManager:
except asyncio.CancelledError:
raise
except Exception as exc:
+ message = _provider_query_failure_reason(exc)
logger.warning(
"Provider model discovery skipped: provider={} reason={}",
provider_id,
- _provider_query_failure_reason(exc, generation.settings),
+ message,
+ )
+ result = ProviderModelRefreshResult(
+ failed_provider_ids=(provider_id,),
+ failure_messages={provider_id: message},
)
- result = ProviderModelRefreshResult(failed_provider_ids=(provider_id,))
else:
self._cache_result(generation, provider_id, infos)
logger.info(
@@ -368,6 +372,12 @@ class ProviderRuntimeManager:
if isinstance(result, ProviderModelRefreshResult)
for provider in result.failed_provider_ids
),
+ failure_messages={
+ provider: message
+ for result in results
+ if isinstance(result, ProviderModelRefreshResult)
+ for provider, message in result.failure_messages.items()
+ },
)
def start_model_list_refresh(self) -> None:
@@ -464,7 +474,10 @@ class ProviderRuntimeManager:
def catalog_status(self) -> JsonObject:
generation = self._current
providers: JsonObject = {}
- for provider_id in generation.initial_ids:
+ errors: JsonObject = {}
+ for provider_id in dict.fromkeys(
+ (*generation.initial_ids, *generation.catalog_tasks)
+ ):
task = generation.catalog_tasks.get(provider_id)
if task is None or not task.done():
state = "starting"
@@ -472,6 +485,8 @@ class ProviderRuntimeManager:
state = "failed"
else:
state = "failed" if task.result().failed_provider_ids else "ready"
+ if message := task.result().failure_messages.get(provider_id):
+ errors[provider_id] = message
providers[provider_id] = state
return {
"generation_id": generation.generation_id,
@@ -479,6 +494,7 @@ class ProviderRuntimeManager:
"catalog": "ready" if generation.initial_complete else "starting",
"catalog_file": generation.file_state,
"providers": providers,
+ "provider_errors": errors,
}
async def connected_provider_changed(
diff --git a/tests/api/test_admin.py b/tests/api/test_admin.py
index 507bf179..f9478335 100644
--- a/tests/api/test_admin.py
+++ b/tests/api/test_admin.py
@@ -2410,6 +2410,26 @@ def test_admin_provider_test_route_preserves_runtime_result(
assert response.json() == result
+def test_admin_provider_test_exposes_completed_attempt_failure():
+ app = create_test_app()
+ manager = provider_manager_for_app(app)
+ message = "The model-list request returned HTTP 403."
+ result = ProviderModelRefreshResult(
+ failed_provider_ids=("nvidia_nim",),
+ failure_messages={"nvidia_nim": message},
+ )
+ with patch.object(manager, "refresh_provider", new=AsyncMock(return_value=result)):
+ response = _local_client(app).post(
+ "/admin/api/providers/nvidia_nim/test", json={}
+ )
+ assert response.status_code == 200
+ assert response.json() == {
+ "provider_id": "nvidia_nim",
+ "ok": False,
+ "message": message,
+ }
+
+
def test_admin_launch_url_uses_loopback_for_wildcard_host():
settings = Settings.model_construct(host="0.0.0.0", port=8082)
diff --git a/tests/cli/test_doctor.py b/tests/cli/test_doctor.py
index 28106732..55c4e9c9 100644
--- a/tests/cli/test_doctor.py
+++ b/tests/cli/test_doctor.py
@@ -3,6 +3,7 @@ import os
import subprocess
import sys
+import httpx
import pytest
from free_claude_code.cli import doctor
@@ -14,6 +15,169 @@ from free_claude_code.providers.openai_codex import auth as openai_auth
from free_claude_code.runtime import diagnostics
[email protected](autouse=True)
+def offline_discovery_status(monkeypatch):
+ def unavailable(*args, **kwargs):
+ raise httpx.ConnectError("private-canary")
+
+ monkeypatch.setattr(httpx, "get", unavailable)
+
+
+def test_live_discovery_report_projects_only_safe_current_errors(monkeypatch):
+ requests = []
+ message = "The network proxy rejected or failed the connection. Check your proxy settings."
+
+ def get(url, **kwargs):
+ requests.append((url, kwargs))
+ return httpx.Response(
+ 200,
+ request=httpx.Request("GET", url),
+ json={
+ "status": "running",
+ "token": "private-canary",
+ "startup": {
+ "providers": {
+ "nvidia_nim": "failed",
+ "open_router": "ready",
+ "private-canary": "failed",
+ },
+ "provider_errors": {
+ "nvidia_nim": message,
+ "open_router": "private-canary",
+ },
+ },
+ },
+ )
+
+ monkeypatch.setattr(httpx, "get", get)
+ result = diagnostics.model_discovery_report(Settings())
+ assert result["status"] == "available"
+ assert result["providers"]["nvidia_nim"] == {"state": "failed", "message": message}
+ assert result["providers"]["open_router"] == {"state": "ready"}
+ assert "private-canary" not in json.dumps(result)
+ assert requests == [
+ (
+ "http://127.0.0.1:8082/admin/api/status",
+ {
+ "timeout": 2.0,
+ "trust_env": False,
+ "follow_redirects": False,
+ },
+ )
+ ]
+
+
+ "payload",
+ [
+ None,
+ [],
+ {},
+ {"status": "running"},
+ {"status": "running", "startup": {"providers": []}},
+ ],
+)
+def test_missing_or_incompatible_live_status_is_unavailable(monkeypatch, payload):
+ monkeypatch.setattr(
+ httpx,
+ "get",
+ lambda url, **kwargs: httpx.Response(
+ 200, request=httpx.Request("GET", url), json=payload
+ ),
+ )
+ assert diagnostics.model_discovery_report(Settings())["status"] == "unavailable"
+
+
+ "message",
+ [
+ "private-canary",
+ "The model-list request returned HTTP 403. private-canary",
+ {},
+ None,
+ ],
+)
+def test_doctor_does_not_trust_arbitrary_server_failure_text(monkeypatch, message):
+ monkeypatch.setattr(
+ httpx,
+ "get",
+ lambda url, **kwargs: httpx.Response(
+ 200,
+ request=httpx.Request("GET", url),
+ json={
+ "status": "running",
+ "startup": {
+ "providers": {"nvidia_nim": "failed"},
+ "provider_errors": {"nvidia_nim": message},
+ },
+ },
+ ),
+ )
+ result = diagnostics.model_discovery_report(Settings())
+ assert result["providers"]["nvidia_nim"] == {
+ "state": "failed",
+ "message": "Could not load models. Check the provider's settings and retry.",
+ }
+ assert "private-canary" not in json.dumps(result)
+
+
+ "status, body",
+ [(302, "private-canary"), (500, "private-canary"), (200, "private-canary")],
+)
+def test_unusable_local_http_response_is_unavailable(monkeypatch, status, body):
+ monkeypatch.setattr(
+ httpx,
+ "get",
+ lambda url, **kwargs: httpx.Response(
+ status,
+ request=httpx.Request("GET", url),
+ text=body,
+ headers={"Location": "https://private-canary.test"},
+ ),
+ )
+ result = diagnostics.model_discovery_report(Settings())
+ assert result["status"] == "unavailable"
+ assert "private-canary" not in json.dumps(result)
+
+
+def test_discovery_status_failure_does_not_expose_exception_or_contact_remote_host(
+ monkeypatch,
+):
+ assert diagnostics.model_discovery_report(Settings())["status"] == "unavailable"
+
+ def forbidden(*args, **kwargs):
+ pytest.fail("doctor must only contact the local server")
+
+ monkeypatch.setattr(httpx, "get", forbidden)
+ assert (
+ diagnostics.model_discovery_report(Settings(HOST="remote.test"))["status"]
+ == "unavailable"
+ )
+
+
+ "host", ["http://127.0.0.1", "[::1", "[::1]:8082", "local\nhost"]
+)
+def test_malformed_host_still_produces_a_doctor_report(monkeypatch, host):
+ ManagedConfigStore().initialize({})
+ monkeypatch.setenv("HOST", host)
+
+ # Exercise real URL validation without connecting to a user-owned server.
+ def validate_url(url, **kwargs):
+ httpx.Request("GET", url)
+ raise httpx.ConnectError("unavailable")
+
+ monkeypatch.setattr(httpx, "get", validate_url)
+ monkeypatch.setattr(diagnostics, "harness_report", lambda: {})
+ monkeypatch.setattr(diagnostics, "integration_report", lambda settings: {})
+ report = diagnostics.collect_report()
+ assert report["configuration"]["status"] == "available"
+ assert report["runtime"]["host"] == host
+ assert report["model_discovery"]["status"] == "unavailable"
+ assert json.dumps(report)
+
+
def test_missing_configuration_still_produces_report(monkeypatch):
monkeypatch.setattr(diagnostics, "harness_report", lambda: {})
report = diagnostics.collect_report()
@@ -116,6 +280,7 @@ def test_complete_report_reads_real_files_without_mutation(
assert report["integrations"]["claude-vscode"]["connected"] is True
assert report["providers"]["github_copilot"]["saved_connection"] == "connected"
assert report["errors"] == []
+ assert report["model_discovery"]["status"] == "unavailable"
assert all(not item["installed"] for item in report["harnesses"].values())
for private in (
"managed-secret",
diff --git a/tests/providers/test_credential_validation.py b/tests/providers/test_credential_validation.py
index 24907bc6..af431920 100644
--- a/tests/providers/test_credential_validation.py
+++ b/tests/providers/test_credential_validation.py
@@ -253,6 +253,16 @@ async def test_unsupported_shared_credentials_never_send_http(monkeypatch):
assert all(
check.status == validation.CredentialStatus.UNVERIFIED for check in result
)
+ nim = next(check for check in result if check.key == "NVIDIA_NIM_API_KEY")
+ assert nim.message == "Automatic verification is unavailable for NVIDIA NIM."
+ assert "saved" not in nim.message.lower()
+ messages = {check.key: check.message for check in result}
+ assert messages["OPENCODE_API_KEY"] == (
+ "Automatic verification is unavailable for OpenCode Zen and OpenCode Go."
+ )
+ assert messages["ZAI_API_KEY"] == (
+ "Automatic verification is unavailable for Z.ai Coding Plan and Z.ai API."
+ )
@pytest.mark.asyncio
diff --git a/tests/providers/test_discovery_errors.py b/tests/providers/test_discovery_errors.py
new file mode 100644
index 00000000..024698bb
--- /dev/null
+++ b/tests/providers/test_discovery_errors.py
@@ -0,0 +1,153 @@
+"""Shareable discovery errors retain transport causes without upstream secrets."""
+
+import socket
+import ssl
+from unittest.mock import AsyncMock
+
+import anyio
+import anyio.streams.tls
+import httpx
+import httpx2
+import openai
+import pytest
+
+from free_claude_code.application.errors import ApplicationUnavailableError
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
+from free_claude_code.providers.admission import (
+ ProviderAdmissionController,
+ ProviderOperationKind,
+)
+from free_claude_code.providers.failure_policy import ProviderRecoveryExhausted
+from free_claude_code.providers.model_listing import ModelListResponseError
+from free_claude_code.providers.runtime.discovery import _provider_query_failure_reason
+
+
+ "cause, expected",
+ [
+ (httpx2.ProxyError("400 Bad Request secret-canary"), "proxy"),
+ (httpx.ProxyError("secret-canary"), "proxy"),
+ (socket.gaierror(-2, "secret-canary"), "DNS"),
+ (ssl.SSLCertVerificationError(1, "secret-canary"), "certificate"),
+ (ssl.SSLError("secret-canary"), "TLS"),
+ (httpx2.ReadTimeout("secret-canary"), "timed out"),
+ (httpx.ConnectError("secret-canary"), "connect"),
+ (ModelListResponseError("secret-canary"), "invalid model list"),
+ (ApplicationUnavailableError("secret-canary"), "unavailable"),
+ (
+ ExecutionFailure(FailureKind.TIMEOUT, 504, "secret-canary", True),
+ "timed out",
+ ),
+ ],
+)
+def test_wrapped_discovery_errors_are_specific_and_secret_safe(cause, expected):
+ error = openai.APIConnectionError(
+ message="secret-canary", request=httpx2.Request("GET", "https://example.test")
+ )
+ error.__cause__ = cause
+ message = _provider_query_failure_reason(error)
+ assert expected in message
+ assert "secret-canary" not in message
+
+
+def test_sdk_status_error_preserves_status_without_body():
+ response = httpx2.Response(
+ 401, request=httpx2.Request("GET", "https://example.test")
+ )
+ error = openai.APIStatusError(
+ "secret-canary", response=response, body={"secret": "secret-canary"}
+ )
+ assert (
+ _provider_query_failure_reason(error)
+ == "The model-list request returned HTTP 401."
+ )
+
+
+ "failure, expected", [("dns", "DNS"), ("certificate", "certificate")]
+)
+async def test_sdk_connection_pool_preserves_os_failure_diagnostics(
+ monkeypatch, failure, expected
+):
+ stream = AsyncMock(spec=anyio.abc.ByteStream)
+ connect = AsyncMock(return_value=stream)
+ if failure == "dns":
+ connect.side_effect = socket.gaierror(-2, "secret-canary")
+ monkeypatch.setattr(anyio, "connect_tcp", connect)
+ monkeypatch.setattr(
+ anyio.streams.tls.TLSStream,
+ "wrap",
+ AsyncMock(side_effect=ssl.SSLCertVerificationError(1, "secret-canary")),
+ )
+ async with openai.AsyncOpenAI(
+ api_key="secret-canary",
+ base_url="https://provider.invalid/v1",
+ max_retries=0,
+ http_client=httpx2.AsyncClient(trust_env=False),
+ ) as client:
+ with pytest.raises(openai.APIConnectionError) as caught:
+ await client.models.list()
+ message = _provider_query_failure_reason(caught.value)
+ assert expected in message
+ assert "secret-canary" not in message
+
+
[email protected]("client", [httpx, httpx2])
+def test_http_status_is_preserved_without_url_body_or_exception_message(client):
+ request = client.Request("GET", "https://user:[email protected]/models")
+ response = client.Response(403, request=request, text="secret-canary")
+ error = client.HTTPStatusError("secret-canary", request=request, response=response)
+ message = _provider_query_failure_reason(error)
+ assert "HTTP 403" in message
+ assert "secret-canary" not in message
+
+
+def test_exception_context_and_cycles_are_safe():
+ error = RuntimeError("secret-canary")
+ cause = socket.gaierror(-2, "secret-canary")
+ error.__context__ = cause
+ cause.__context__ = error
+ assert "DNS" in _provider_query_failure_reason(error)
+ error.__suppress_context__ = True
+ message = _provider_query_failure_reason(error)
+ assert "DNS" in message
+ assert "secret-canary" not in message
+
+
+ "error", [httpx2.ReadTimeout("secret-canary"), httpx2.ConnectError("secret-canary")]
+)
+async def test_real_admission_cooldown_retains_discovery_failure(error):
+ controller = ProviderAdmissionController(
+ provider_name="TEST",
+ max_attempts=1,
+ base_delay=30,
+ max_delay=30,
+ jitter=0,
+ )
+ fetch = AsyncMock(side_effect=error)
+ with pytest.raises(type(error)):
+ await controller.start_execution().run_call(
+ fetch, operation_kind=ProviderOperationKind.MODEL_DISCOVERY
+ )
+ with pytest.raises(ProviderRecoveryExhausted) as cooldown:
+ await controller.start_execution().run_call(
+ fetch, operation_kind=ProviderOperationKind.MODEL_DISCOVERY
+ )
+ fetch.assert_awaited_once()
+ assert cooldown.value.__cause__ is None
+ assert cooldown.value.__context__ is None
+ assert _provider_query_failure_reason(
+ cooldown.value
+ ) == _provider_query_failure_reason(error)
+
+
+def test_recovery_wrapper_cycles_do_not_hang_classification():
+ wrapper = ProviderRecoveryExhausted(RuntimeError("secret-canary"))
+ wrapper.last_error = wrapper
+ assert (
+ _provider_query_failure_reason(wrapper)
+ == "Could not load models. Check the provider's settings and retry."
+ )
diff --git a/tests/providers/test_model_discovery.py b/tests/providers/test_model_discovery.py
index 6fa30b37..bd07166e 100644
--- a/tests/providers/test_model_discovery.py
+++ b/tests/providers/test_model_discovery.py
@@ -576,7 +576,8 @@ async def test_runtime_warm_reports_query_failures_without_blocking() -> None:
assert runtime.cached_model_ids() == {"nvidia_nim": frozenset({"nim-model"})}
logged = " ".join(str(arg) for call in warning.call_args_list for arg in call.args)
assert "open_router" in logged
- assert "malformed model-list response: bad model-list shape" in logged
+ assert "The provider returned an invalid model list." in logged
+ assert "bad model-list shape" not in logged
@pytest.mark.asyncio
diff --git a/tests/runtime/test_application_runtime.py b/tests/runtime/test_application_runtime.py
index 8df5d3dd..17fd1f22 100644
--- a/tests/runtime/test_application_runtime.py
+++ b/tests/runtime/test_application_runtime.py
@@ -290,10 +290,7 @@ async def test_provider_check_returns_stable_failure_for_application_error() ->
assert result == {
"provider_id": "nvidia_nim",
"ok": False,
- "message": (
- "Could not refresh this provider's models. "
- "Verify its configuration and access."
- ),
+ "message": "The provider is unavailable. Check its configuration and access.",
}
assert "error_type" not in result
await manager.close()
@@ -315,14 +312,12 @@ async def test_provider_check_never_returns_unrecognized_credentials(
assert result == {
"provider_id": "nvidia_nim",
"ok": False,
- "message": (
- "Could not refresh this provider's models. "
- "Verify its configuration and access."
- ),
+ "message": "Could not load models. Check the provider's settings and retry.",
}
log_text = " | ".join(record.getMessage() for record in caplog.records)
assert "provider=nvidia_nim" in log_text
- assert "RuntimeError" in log_text
+ assert isinstance(result["message"], str)
+ assert result["message"] in log_text
assert secret not in log_text
assert "error_type" not in result
await manager.close()
diff --git a/tests/runtime/test_provider_manager.py b/tests/runtime/test_provider_manager.py
index 486e6cfe..4dd4be80 100644
--- a/tests/runtime/test_provider_manager.py
+++ b/tests/runtime/test_provider_manager.py
@@ -2,6 +2,7 @@ import asyncio
from typing import cast
from unittest.mock import AsyncMock, MagicMock, patch
+import httpx2
import pytest
from free_claude_code.application.errors import ApplicationUnavailableError
@@ -80,6 +81,51 @@ def _settings(model: str) -> Settings:
)
+async def test_discovery_error_follows_attempt_and_generation_without_losing_cache():
+ factory = RuntimeFactory()
+ settings = _settings("nvidia_nim/one")
+ manager = ProviderRuntimeManager(settings, runtime_factory=factory)
+ provider = factory.runtimes[0].provider
+ manager.cache_model_infos("nvidia_nim", {ProviderModelInfo("one")})
+ provider.list_model_infos.side_effect = httpx2.ProxyError("secret-canary")
+ try:
+ with patch(
+ "free_claude_code.runtime.provider_manager.logger.warning"
+ ) as warning:
+ result = await manager.refresh_model_list_cache()
+ message = result.failure_messages["nvidia_nim"]
+ assert "proxy" in message
+ assert manager.catalog_status()["provider_errors"] == {"nvidia_nim": message}
+ assert manager.cached_model_ids()["nvidia_nim"] == frozenset({"one"})
+ assert warning.call_args.args[-1] == message
+ assert "secret-canary" not in str(warning.call_args)
+
+ entered, release = asyncio.Event(), asyncio.Event()
+
+ async def held():
+ entered.set()
+ await release.wait()
+ return frozenset({ProviderModelInfo("two")})
+
+ provider.list_model_infos.side_effect = held
+ refresh = asyncio.create_task(manager.refresh_provider("nvidia_nim"))
+ await entered.wait()
+ assert manager.catalog_status()["providers"] == {"nvidia_nim": "starting"}
+ assert manager.catalog_status()["provider_errors"] == {}
+ release.set()
+ assert (await refresh).failure_messages == {}
+ assert manager.catalog_status()["providers"] == {"nvidia_nim": "ready"}
+ provider.list_model_infos.side_effect = httpx2.ProxyError("secret-canary")
+ await manager.refresh_provider("nvidia_nim")
+ await manager.replace(settings, commit=AsyncMock())
+ assert manager.catalog_status()["provider_errors"] == {}
+ await manager.wait_for_catalog()
+ assert manager.catalog_status()["provider_errors"] == {}
+ finally:
+ await manager.close()
+
+
@pytest.mark.asyncio
async def test_startup_generation_lease_and_shutdown_close_exactly_once() -> None:
factory = RuntimeFactory()