OpenHands/OpenHands · warning · Error

Cloud API key or network issue

Error message

Cloud API key or network issue

What it means

Thrown by the cloud-backend probe when the failure is a CORS or network-level error (not a 401). The probe cannot distinguish a wrong/inactive API key from a network block because both manifest as an opaque browser error with no response body, so they collapse into CLOUD_BACKEND_API_KEY_OR_NETWORK_ERROR. Surfaced through the connectivity dot and the backend's lastError field.

Source

Thrown at src/hooks/query/use-backends-health.ts:107

    if (backend.authMode !== "cookie" && !backend.apiKey?.trim()) {
      throw new Error(MISSING_BACKEND_API_KEY_ERROR);
    }

    try {
      if (backend.authMode === "cookie") {
        await getCloudOrganizations(backend);
      } else {
        await getCurrentCloudApiKey(backend);
      }
    } catch (error) {
      if (
        (axios.isAxiosError(error) && error.response?.status === 401) ||
        (error instanceof HttpError && error.status === 401)
      ) {
        throw new Error(CLOUD_BACKEND_LOGGED_OUT_ERROR);
      }
      if (isCorsOrNetworkError(error)) {
        throw new Error(CLOUD_BACKEND_API_KEY_OR_NETWORK_ERROR);
      }
      throw error;
    }
    return true;
  }

  try {
    const clientOptions = getAgentServerClientOptions({
      host: backend.host,
      sessionApiKey: backend.apiKey || null,
      timeout: PROBE_TIMEOUT_MS,
    });

    await new SettingsClient(clientOptions).getSettings();
    const serverInfo = await new ServerClient(clientOptions).getServerInfo();
    assertAgentServerVersionIsSupported(serverInfo);
  } catch (error) {
    if (isSdkHttpStatusError(error, 401)) {

View on GitHub (pinned to 500b4c533e)

Solutions

1. Verify network connectivity to the cloud host (open the host URL in the same browser).
2. Double-check the cloud backend's host string for typos or a missing region prefix.
3. If behind a corporate proxy, allowlist the cloud origin.
4. Regenerate the cloud API key and paste it without surrounding whitespace.
5. Confirm PROBE_TIMEOUT_MS (4s) is sufficient for the link — increase it if on a slow connection.

// Pre-flight reachability check (best-effort, not authoritative)
async function cloudHostReachable(host: string): Promise<boolean> {
  try {
    await fetch(`${host}/api/v1/health`, { mode: 'no-cors' });
    return true;
  } catch { return false; }
}

function isCloudApiKeyOrNetworkError(error: unknown): boolean {
  return error instanceof Error && error.message === 'Cloud API key or network issue';
}

try {
  await probeBackend(cloudBackend);
} catch (error) {
  if (isCloudApiKeyOrNetworkError(error)) {
    // isRetryableProbeError returns true for this, so probeBackendWithQuickRetry already retried twice
    // surface a 'check network / key' recovery affordance in the UI
  } else throw error;
}

When it happens

Trigger: Cloud probe where axios/fetch throws and isCorsOrNetworkError(error) is true (no response.status, ERR_NETWORK, ECONNABORTED, or a CORS-blocked response). Happens with an unreachable cloud host, an invalid API key whose 4xx is swallowed by CORS, a corporate proxy blocking the cloud origin, or a request timeout against PROBE_TIMEOUT_MS (4s).

Common situations: Wrong base URL for the cloud backend (typo, missing region prefix); corporate firewall/proxy blocks the cloud host; browser offline; cloud API key with leading/trailing whitespace; CSP/CORS rejection from an embedding host origin; DNS failure for the cloud host.

Related errors

• API key required
• Logged out
• Could not connect to the configured agent server. Make sure
• Conversation sandbox is still starting. Wait for it to finis
• Conversation sandbox is still starting. Wait for it to finis

AI-assisted analysis of OpenHands/OpenHands@500b4c533e (2026-08-12). Data as JSON: /api/errors/0e8f0096344493c3. Report an issue: GitHub.