Skip to content

πŸ™Œ OpenHands: AI-Driven Development

fix: validate api key before advancing backend connection step (#16840)

Jatin Jain1697faa31337
diff --git a/__tests__/components/backends/add-backend-modal.test.tsx b/__tests__/components/backends/add-backend-modal.test.tsx
index f8d1ebe6a6..ad56c83882 100644
--- a/__tests__/components/backends/add-backend-modal.test.tsx
+++ b/__tests__/components/backends/add-backend-modal.test.tsx
@@ -14,6 +14,7 @@ import { AddBackendModal } from "#/components/features/backends/add-backend-moda
import * as telemetry from "#/services/telemetry";
const getServerInfoMock = vi.hoisted(() => vi.fn());
+const getSettingsMock = vi.hoisted(() => vi.fn().mockResolvedValue({}));
const deviceFlowMocks = vi.hoisted(() => ({
startDeviceFlow: vi.fn(),
@@ -38,6 +39,11 @@ vi.mock("@openhands/typescript-client/clients", () => ({
getServerInfo: getServerInfoMock,
};
}),
+ SettingsClient: vi.fn(function SettingsClientMock() {
+ return {
+ getSettings: getSettingsMock,
+ };
+ }),
}));
let captureMock: MockInstance<typeof telemetry.trackEvent>;
@@ -89,7 +95,7 @@ beforeEach(() => {
interval: 5,
});
deviceFlowMocks.pollForToken.mockReset();
- deviceFlowMocks.pollForToken.mockImplementation(() => new Promise(() => {}));
+ deviceFlowMocks.pollForToken.mockImplementation(() => new Promise(() => { }));
__resetActiveStoreForTests();
});
diff --git a/__tests__/components/backends/backend-form-modal.test.tsx b/__tests__/components/backends/backend-form-modal.test.tsx
index 494d51c831..04c7cd0a39 100644
--- a/__tests__/components/backends/backend-form-modal.test.tsx
+++ b/__tests__/components/backends/backend-form-modal.test.tsx
@@ -16,6 +16,7 @@ import {
import { BackendFormModal } from "#/components/features/backends/backend-form-modal";
const getServerInfoMock = vi.hoisted(() => vi.fn());
+const getSettingsMock = vi.hoisted(() => vi.fn().mockResolvedValue({}));
vi.mock("@openhands/typescript-client/clients", () => ({
ServerClient: vi.fn(function ServerClientMock() {
@@ -23,6 +24,11 @@ vi.mock("@openhands/typescript-client/clients", () => ({
getServerInfo: getServerInfoMock,
};
}),
+ SettingsClient: vi.fn(function SettingsClientMock() {
+ return {
+ getSettings: getSettingsMock,
+ };
+ }),
}));
function renderWithProviders(
diff --git a/__tests__/components/onboarding/onboarding-modal.test.tsx b/__tests__/components/onboarding/onboarding-modal.test.tsx
index b369919e64..be09c02be6 100644
--- a/__tests__/components/onboarding/onboarding-modal.test.tsx
+++ b/__tests__/components/onboarding/onboarding-modal.test.tsx
@@ -23,6 +23,7 @@ import * as telemetry from "#/services/telemetry";
const llmSettingsScreenMock = vi.hoisted(() => vi.fn());
const getServerInfoMock = vi.hoisted(() => vi.fn());
+const getSettingsMock = vi.hoisted(() => vi.fn().mockResolvedValue({}));
let captureMock: MockInstance<typeof telemetry.trackEvent>;
// Both the backend status badge in the embedded edit form and the
@@ -38,7 +39,7 @@ vi.mock("@openhands/typescript-client/clients", () => ({
// `LlmSettingsScreen` is stubbed, so provide the minimal client it needs.
SettingsClient: vi.fn(function SettingsClientMock() {
return {
- getSettings: vi.fn().mockResolvedValue({}),
+ getSettings: vi.fn(() => getSettingsMock()),
};
}),
}));
@@ -618,6 +619,47 @@ describe("OnboardingModal", () => {
expect(screen.queryByText("BACKEND$LOGIN_OR")).toBeNull();
});
+ it("shows a connection error when the backend API key is invalid", async () => {
+ window.localStorage.clear();
+ vi.stubEnv("VITE_BACKEND_BASE_URL", "");
+ vi.stubEnv("VITE_SESSION_API_KEY", "");
+ delete (window as unknown as Record<string, unknown>)
+ .__AGENT_CANVAS_SESSION_API_KEY__;
+ __resetActiveStoreForTests();
+
+ // Mock SettingsClient to throw a 401 error
+ const authError = new Error("Unauthorized");
+ authError.name = "HttpError";
+ (authError as any).status = 401;
+ getSettingsMock.mockRejectedValueOnce(authError);
+ // getServerInfoMock implicitly resolves, but shouldn't be reached if test is correct
+
+ renderModal();
+ const user = userEvent.setup();
+
+ await user.clear(screen.getByTestId("onboarding-backend-host"));
+ await user.type(
+ screen.getByTestId("onboarding-backend-host"),
+ "https://127.0.0.1:8000",
+ );
+ await user.clear(screen.getByTestId("onboarding-backend-api-key"));
+ await user.type(
+ screen.getByTestId("onboarding-backend-api-key"),
+ "invalid-session-key",
+ );
+ await user.click(screen.getByTestId("onboarding-backend-next"));
+
+ expect(
+ await screen.findByTestId("onboarding-backend-error"),
+ ).toHaveTextContent("BACKEND$CONNECTION_TEST_FAILED");
+ expect(screen.getByTestId("onboarding-backend-error")).toHaveTextContent(
+ "Invalid API key", // This comes from INVALID_BACKEND_API_KEY_ERROR
+ );
+
+ // Should not advance to the next step
+ expect(screen.queryByText("BACKEND$LOGIN_OR")).toBeNull();
+ });
+
it("shows a connection error when saving an unreachable backend", async () => {
window.localStorage.clear();
vi.stubEnv("VITE_BACKEND_BASE_URL", "");
@@ -977,7 +1019,7 @@ describe("OnboardingModal", () => {
);
expect(
helloInput.compareDocumentPosition(recommendations) &
- Node.DOCUMENT_POSITION_FOLLOWING,
+ Node.DOCUMENT_POSITION_FOLLOWING,
).toBeTruthy();
expect(
within(recommendations).getByTestId(
diff --git a/src/api/agent-server-compatibility.ts b/src/api/agent-server-compatibility.ts
index efd7897e97..a2834b6423 100644
--- a/src/api/agent-server-compatibility.ts
+++ b/src/api/agent-server-compatibility.ts
@@ -10,6 +10,7 @@ import {
getEffectiveLocalBackend,
isNoBackend,
} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
import defaults from "../../config/defaults.json";
const AGENT_SERVER_INFO_TIMEOUT_MS = 5000;
@@ -22,6 +23,14 @@ export const AGENT_SERVER_UNSUPPORTED_VERSION_ERROR_CODE =
export const AGENT_SERVER_UNKNOWN_VERSION_ERROR_CODE =
"AGENT_SERVER_UNKNOWN_VERSION";
+/**
+ * Sentinel string thrown (as an Error message) when a local backend
+ * rejects the configured session API key with HTTP 401.
+ * Shared between the backend health probe ({@link validateLocalBackend})
+ * and any consumer that needs to detect this specific failure.
+ */
+export const INVALID_BACKEND_API_KEY_ERROR = "Invalid API key";
+
export interface AgentServerInfo extends BaseServerInfo {
sdk_version?: string;
usable_tools?: string[] | null;
@@ -317,6 +326,41 @@ export function assertAgentServerVersionIsSupported(
}
}
+/**
+ * Validates a local agent-server backend with a two-step probe:
+ * 1. GET /api/settings β€” authenticates the configured session API key;
+ * a 401 throws an Error with message {@link INVALID_BACKEND_API_KEY_ERROR}.
+ * 2. GET /server_info β€” asserts the server meets the minimum version floor.
+ *
+ * Returns the display version string reported by the server, or `null` when
+ * the server does not report a parseable version. Throws on any failure.
+ *
+ * Used by both the backend health poller and the backend-form connection test
+ * so that auth-check semantics (status codes, error messages) stay in one place.
+ */
+export async function validateLocalBackend(
+ backend: Pick<Backend, "host" | "apiKey">,
+ timeout: number,
+): Promise<string | null> {
+ const clientOptions = getAgentServerClientOptions({
+ host: backend.host,
+ sessionApiKey: backend.apiKey || null,
+ timeout,
+ });
+
+ try {
+ await new SettingsClient(clientOptions).getSettings();
+ const serverInfo = await new ServerClient(clientOptions).getServerInfo();
+ assertAgentServerVersionIsSupported(serverInfo);
+ return getDisplayAgentServerVersion(serverInfo);
+ } catch (error) {
+ if (isSdkHttpStatusError(error, 401)) {
+ throw new Error(INVALID_BACKEND_API_KEY_ERROR);
+ }
+ throw error;
+ }
+}
+
export async function loadAgentServerInfo() {
// The probe is a *local* agent-server concern β€” it verifies the runtime
// hosting the GUI is reachable. It must NEVER run against the active
diff --git a/src/components/features/backends/backend-form-modal.tsx b/src/components/features/backends/backend-form-modal.tsx
index 652db065e8..a302aa5629 100644
--- a/src/components/features/backends/backend-form-modal.tsx
+++ b/src/components/features/backends/backend-form-modal.tsx
@@ -22,8 +22,8 @@ import { getAgentServerClientOptions } from "#/api/agent-server-client-options";
import { getLockedCloudHost } from "#/api/agent-server-config";
import { isOpenHandsCloudHost } from "#/api/device-flow-client";
import {
- assertAgentServerVersionIsSupported,
getDisplayAgentServerVersion,
+ validateLocalBackend,
} from "#/api/agent-server-compatibility";
import ChevronDownSmallIcon from "#/icons/chevron-down-small.svg?react";
import { I18nKey } from "#/i18n/declaration";
@@ -182,16 +182,8 @@ async function testBackendConnection(
): Promise<BackendConnectionTestMetadata> {
// Cloud backends authenticate via OAuth; preflight GET is not applicable.
if (backend.kind !== "local") return { agentServerVersion: null };
-
- const serverInfo = await new ServerClient(
- getAgentServerClientOptions({
- host: backend.host,
- sessionApiKey: backend.apiKey || null,
- timeout: 5000,
- }),
- ).getServerInfo();
- assertAgentServerVersionIsSupported(serverInfo);
- return { agentServerVersion: getDisplayAgentServerVersion(serverInfo) };
+ const agentServerVersion = await validateLocalBackend(backend, 5000);
+ return { agentServerVersion };
}
/**
diff --git a/src/hooks/query/use-backends-health.ts b/src/hooks/query/use-backends-health.ts
index 7526fcfdcb..d495830b19 100644
--- a/src/hooks/query/use-backends-health.ts
+++ b/src/hooks/query/use-backends-health.ts
@@ -2,20 +2,15 @@ import React from "react";
import axios from "axios";
import { useQueries } from "@tanstack/react-query";
import { HttpError } from "@openhands/typescript-client";
-import {
- ServerClient,
- SettingsClient,
-} from "@openhands/typescript-client/clients";
import {
getCloudOrganizations,
getCurrentCloudApiKey,
} from "#/api/cloud/organization-service.api";
import {
- assertAgentServerVersionIsSupported,
- isSdkHttpStatusError,
+ validateLocalBackend,
+ INVALID_BACKEND_API_KEY_ERROR,
} from "#/api/agent-server-compatibility";
import type { Backend } from "#/api/backend-registry/types";
-import { getAgentServerClientOptions } from "#/api/agent-server-client-options";
import {
isCorsOrNetworkError,
isCorsOrNetworkErrorMessage,
@@ -33,7 +28,7 @@ import { MAX_CONSECUTIVE_FAILURES } from "#/api/backend-registry/health-storage"
// traffic for the browser's per-origin HTTP/1.1 connection pool.
const REFRESH_INTERVAL_MS = 30000;
const PROBE_TIMEOUT_MS = 4000;
-export const INVALID_BACKEND_API_KEY_ERROR = "Invalid API key";
+export { INVALID_BACKEND_API_KEY_ERROR } from "#/api/agent-server-compatibility";
export const MISSING_BACKEND_API_KEY_ERROR = "API key required";
export const CLOUD_BACKEND_API_KEY_OR_NETWORK_ERROR =
"Cloud API key or network issue";
@@ -114,22 +109,7 @@ async function probeBackend(backend: Backend): Promise<true> {
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)) {
- throw new Error(INVALID_BACKEND_API_KEY_ERROR);
- }
- throw error;
- }
+ await validateLocalBackend(backend, PROBE_TIMEOUT_MS);
return true;
}