Skip to content

🙌 OpenHands: AI-Driven Development

fix(mcp): explain failed stdio connection tests without the URL hint (#18018)

Engel Nyst60444de16ae8
diff --git a/__tests__/components/features/mcp-page/custom-server-editor.test.tsx b/__tests__/components/features/mcp-page/custom-server-editor.test.tsx
index ae1037c01f..6dfe2e3086 100644
--- a/__tests__/components/features/mcp-page/custom-server-editor.test.tsx
+++ b/__tests__/components/features/mcp-page/custom-server-editor.test.tsx
@@ -303,6 +303,30 @@ describe("CustomServerEditor", () => {
);
});
+ it("explains a stdio connection failure from Test connection as a command that could not start", async () => {
+ // Arrange: editing an installed stdio server whose command cannot spawn.
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+ buildSettingsWithMcp(),
+ );
+ vi.spyOn(McpService, "testServer").mockResolvedValue({
+ ok: false,
+ error: "Client failed to connect: [Errno 2] No such file or directory",
+ error_kind: "connection",
+ });
+ renderWith(<EditEditorOnceSettingsLoaded onClose={vi.fn()} />);
+ await screen.findByTestId("mcp-custom-editor");
+
+ // Act
+ fireEvent.click(screen.getByTestId("mcp-test-connection"));
+
+ // Assert: the stdio-specific message, not the URL hint.
+ await waitFor(() =>
+ expect(screen.getByTestId("mcp-test-message")).toHaveTextContent(
+ "MCP$TEST_ERROR_STDIO_START",
+ ),
+ );
+ });
+
it("offers Test connection for remote servers on cloud backends and shows the result", async () => {
// Arrange: a cloud backend is active and the probe (routed through the
// app server) succeeds.
diff --git a/__tests__/components/features/mcp-page/install-server-modal.test.tsx b/__tests__/components/features/mcp-page/install-server-modal.test.tsx
index 3bb525f155..06e7e57b89 100644
--- a/__tests__/components/features/mcp-page/install-server-modal.test.tsx
+++ b/__tests__/components/features/mcp-page/install-server-modal.test.tsx
@@ -720,9 +720,11 @@ describe("InstallServerModal", () => {
fireEvent.click(screen.getByTestId("mcp-install-submit"));
- // Error message must appear.
+ // The remote-server connection message must appear.
await waitFor(() =>
- expect(screen.getByTestId("mcp-install-modal-error")).toBeInTheDocument(),
+ expect(screen.getByTestId("mcp-install-modal-error")).toHaveTextContent(
+ "MCP$TEST_ERROR_CONNECTION",
+ ),
);
// Save must never have been called.
@@ -733,6 +735,33 @@ describe("InstallServerModal", () => {
expect(screen.getByTestId("mcp-install-modal")).toBeInTheDocument();
});
+ it("explains a stdio pre-flight connection failure as a command that could not start", async () => {
+ // Arrange: a stdio catalog entry whose command the Agent Server cannot spawn.
+ vi.spyOn(McpService, "testServer").mockResolvedValue({
+ ok: false,
+ error: "Client failed to connect: [Errno 2] No such file or directory",
+ error_kind: "connection",
+ });
+ const saveSpy = vi
+ .spyOn(SettingsService, "saveSettings")
+ .mockResolvedValue(true);
+ const time = MCP_MARKETPLACE.find((e) => e.id === "time")!;
+ renderWith(<InstallServerModal existingServers={[]} entry={time} onClose={vi.fn()} />);
+ await screen.findByTestId("mcp-install-modal");
+ await waitFor(() => expect(SettingsService.getSettings).toHaveBeenCalled());
+
+ // Act
+ fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+ // Assert: the stdio-specific message, not the URL hint, and nothing saved.
+ await waitFor(() =>
+ expect(screen.getByTestId("mcp-install-modal-error")).toHaveTextContent(
+ "MCP$TEST_ERROR_STDIO_START",
+ ),
+ );
+ expect(saveSpy).not.toHaveBeenCalled();
+ });
+
it("shows the credential-specific message when the pre-flight test reports invalid credentials", async () => {
// Arrange: installing Slack with credentials its verification call
// rejects (the service maps Slack's invalid_auth to "credentials").
diff --git a/__tests__/components/features/mcp-page/mcp-server-health.test.tsx b/__tests__/components/features/mcp-page/mcp-server-health.test.tsx
index 257a9cfada..35b224d5a7 100644
--- a/__tests__/components/features/mcp-page/mcp-server-health.test.tsx
+++ b/__tests__/components/features/mcp-page/mcp-server-health.test.tsx
@@ -159,6 +159,30 @@ describe("InstalledServerCard connection health", () => {
);
});
+ it.each([
+ { server: STDIO_SERVER, expectedLabel: "MCP$TEST_ERROR_STDIO_START" },
+ { server: CUSTOM_SERVER, expectedLabel: "MCP$TEST_ERROR_CONNECTION" },
+ ])(
+ "labels a $server.type connection failure with transport-specific copy",
+ async ({ server, expectedLabel }) => {
+ vi.spyOn(McpService, "testServer").mockResolvedValue({
+ ok: false,
+ error: "Client failed to connect",
+ error_kind: "connection",
+ });
+ renderCard(server);
+
+ fireEvent.click(probeButton(server.id));
+
+ // i18n keys are returned as-is in tests.
+ await waitFor(() =>
+ expect(screen.getByTestId(`mcp-health-label-${server.id}`)).toHaveTextContent(
+ expectedLabel,
+ ),
+ );
+ },
+ );
+
it("renders the health section for remote servers on cloud backends", () => {
setRegisteredBackends([
{
diff --git a/__tests__/utils/mcp-test-error-message.test.ts b/__tests__/utils/mcp-test-error-message.test.ts
new file mode 100644
index 0000000000..e5d63e9c33
--- /dev/null
+++ b/__tests__/utils/mcp-test-error-message.test.ts
@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import i18next, { type TFunction } from "i18next";
+import { translationResources } from "#/i18n/resources";
+import { makeMcpTestErrorMessage } from "#/utils/mcp-test-error-message";
+
+// Drive a real i18next instance with the actual en resource so the assertions
+// cover the rendered copy and its interpolation, not just the chosen key.
+const instance = i18next.createInstance();
+instance.init({
+ lng: "en",
+ resources: { en: { openhands: translationResources.en } },
+ ns: ["openhands"],
+ defaultNS: "openhands",
+ interpolation: { escapeValue: false },
+});
+const t = instance.t as unknown as TFunction<"openhands">;
+
+const STDIO_DETAIL =
+ "Client failed to connect: [Errno 2] No such file or directory: 'qa-no-such-command'";
+const REMOTE_DETAIL =
+ "Client failed to connect: All connection attempts failed";
+
+describe("makeMcpTestErrorMessage", () => {
+ it("explains a stdio connection failure as a command that could not start, with the backend detail", () => {
+ const message = makeMcpTestErrorMessage(
+ t,
+ "connection",
+ STDIO_DETAIL,
+ "stdio",
+ );
+
+ expect(message).toBe(`Could not start the server command: ${STDIO_DETAIL}`);
+ expect(message).not.toContain("URL");
+ });
+
+ it.each(["shttp", "sse", undefined] as const)(
+ "keeps the reach-the-server guidance for a %s connection failure and adds the backend detail",
+ (serverType) => {
+ const message = makeMcpTestErrorMessage(
+ t,
+ "connection",
+ REMOTE_DETAIL,
+ serverType,
+ );
+
+ expect(message).toBe(
+ `Could not reach the server (check the URL and server type): ${REMOTE_DETAIL}`,
+ );
+ },
+ );
+
+ it("leaves timeout and credentials failures unchanged for stdio servers", () => {
+ expect(makeMcpTestErrorMessage(t, "timeout", "late", "stdio")).toBe(
+ "Connection timed out. Check the URL and try again.",
+ );
+ expect(
+ makeMcpTestErrorMessage(t, "credentials", "invalid_auth", "stdio"),
+ ).toBe("Credential check failed: invalid_auth");
+ });
+});
diff --git a/src/components/features/mcp-page/custom-server-editor.tsx b/src/components/features/mcp-page/custom-server-editor.tsx
index 5e8d44905b..b35df6cd7d 100644
--- a/src/components/features/mcp-page/custom-server-editor.tsx
+++ b/src/components/features/mcp-page/custom-server-editor.tsx
@@ -85,11 +85,19 @@ export function CustomServerEditor({
text: t(I18nKey.MCP$TEST_SUCCESS, { count: result.tools.length }),
};
}
+ // OAuth results come only from remote servers; `testedServer` may be
+ // left over from an earlier non-OAuth test.
+ const resultServerType = oauthTestResult ? undefined : testedServer?.type;
return {
ok: false,
- text: makeMcpTestErrorMessage(t, result.error_kind, result.error),
+ text: makeMcpTestErrorMessage(
+ t,
+ result.error_kind,
+ result.error,
+ resultServerType,
+ ),
};
- }, [oauthTestResult, testResult, t]);
+ }, [oauthTestResult, testResult, testedServer, t]);
// A save always follows a fresh successful probe of the exact config being
// saved, so publish that result to the card's health entry. For stdio
diff --git a/src/components/features/mcp-page/install-server-modal.tsx b/src/components/features/mcp-page/install-server-modal.tsx
index 17007724ad..652938339d 100644
--- a/src/components/features/mcp-page/install-server-modal.tsx
+++ b/src/components/features/mcp-page/install-server-modal.tsx
@@ -278,7 +278,12 @@ export function InstallServerModal({
.then((result) => {
if (!result.ok) {
setGlobalError(
- makeMcpTestErrorMessage(t, result.error_kind, result.error),
+ makeMcpTestErrorMessage(
+ t,
+ result.error_kind,
+ result.error,
+ payload.type,
+ ),
);
return;
}
@@ -321,7 +326,12 @@ export function InstallServerModal({
onSuccess: (result) => {
if (!result.ok) {
setGlobalError(
- makeMcpTestErrorMessage(t, result.error_kind, result.error),
+ makeMcpTestErrorMessage(
+ t,
+ result.error_kind,
+ result.error,
+ payload.type,
+ ),
);
// Modal stays open — do NOT call onClose.
return;
diff --git a/src/components/features/mcp-page/mcp-server-health.tsx b/src/components/features/mcp-page/mcp-server-health.tsx
index 9ba2ba9269..0554e6725d 100644
--- a/src/components/features/mcp-page/mcp-server-health.tsx
+++ b/src/components/features/mcp-page/mcp-server-health.tsx
@@ -43,6 +43,7 @@ function getDotStatus(health: McpServerHealth): string {
function getStatusLabel(
t: TFunction<"openhands">,
health: McpServerHealth,
+ serverType: MCPServerConfig["type"],
): string {
switch (health.status) {
case "checking":
@@ -52,7 +53,7 @@ function getStatusLabel(
? t(I18nKey.MCP$HEALTH_STATUS_VERIFIED, { count: health.toolCount })
: t(I18nKey.MCP$HEALTH_STATUS_CONNECTIVITY_ONLY);
case "failed":
- return makeMcpTestErrorMessage(t, health.kind, health.error);
+ return makeMcpTestErrorMessage(t, health.kind, health.error, serverType);
default:
return t(I18nKey.MCP$HEALTH_STATUS_UNCHECKED);
}
@@ -82,7 +83,7 @@ export function McpServerHealthSection({
const isChecking = health.status === "checking";
const isFailed = health.status === "failed";
- const label = getStatusLabel(t, health);
+ const label = getStatusLabel(t, health, server.type);
const handleReauthorize = async () => {
const result = await reauthorize();
diff --git a/src/i18n/translation.json b/src/i18n/translation.json
index 041dd8942b..8ae9147eb1 100644
--- a/src/i18n/translation.json
+++ b/src/i18n/translation.json
@@ -17357,21 +17357,38 @@
"uk": "Час очікування з'єднання вичерпано. Перевірте URL-адресу та спробуйте ще раз."
},
"MCP$TEST_ERROR_CONNECTION": {
- "en": "Could not reach the server. Check the URL and server type.",
- "ja": "サーバーに接続できませんでした。URLとサーバーの種類を確認してください。",
- "zh-CN": "无法连接到服务器。请检查 URL 和服务器类型。",
- "zh-TW": "無法連線到伺服器。請檢查 URL 和伺服器類型。",
- "ko-KR": "서버에 연결할 수 없습니다. URL과 서버 유형을 확인하세요.",
- "no": "Kunne ikke nå serveren. Sjekk URL-en og servertypen.",
- "ar": "تعذّر الوصول إلى الخادم. تحقق من عنوان URL ونوع الخادم.",
- "de": "Server konnte nicht erreicht werden. Überprüfen Sie die URL und den Servertyp.",
- "fr": "Impossible d'atteindre le serveur. Vérifiez l'URL et le type de serveur.",
- "it": "Impossibile raggiungere il server. Controlla l'URL e il tipo di server.",
- "pt": "Não foi possível acessar o servidor. Verifique a URL e o tipo de servidor.",
- "es": "No se pudo conectar con el servidor. Comprueba la URL y el tipo de servidor.",
- "ca": "No s'ha pogut connectar amb el servidor. Comprova l'URL i el tipus de servidor.",
- "tr": "Sunucuya ulaşılamadı. URL'yi ve sunucu türünü kontrol edin.",
- "uk": "Не вдалося підключитися до сервера. Перевірте URL-адресу та тип сервера."
+ "en": "Could not reach the server (check the URL and server type): {{-error}}",
+ "ja": "サーバーに接続できませんでした(URLとサーバーの種類を確認してください): {{-error}}",
+ "zh-CN": "无法连接到服务器(请检查 URL 和服务器类型):{{-error}}",
+ "zh-TW": "無法連線到伺服器(請檢查 URL 和伺服器類型):{{-error}}",
+ "ko-KR": "서버에 연결할 수 없습니다(URL과 서버 유형을 확인하세요): {{-error}}",
+ "no": "Kunne ikke nå serveren (sjekk URL-en og servertypen): {{-error}}",
+ "ar": "تعذّر الوصول إلى الخادم (تحقق من عنوان URL ونوع الخادم): {{-error}}",
+ "de": "Server konnte nicht erreicht werden (überprüfen Sie die URL und den Servertyp): {{-error}}",
+ "fr": "Impossible d'atteindre le serveur (vérifiez l'URL et le type de serveur) : {{-error}}",
+ "it": "Impossibile raggiungere il server (controlla l'URL e il tipo di server): {{-error}}",
+ "pt": "Não foi possível acessar o servidor (verifique a URL e o tipo de servidor): {{-error}}",
+ "es": "No se pudo conectar con el servidor (comprueba la URL y el tipo de servidor): {{-error}}",
+ "ca": "No s'ha pogut connectar amb el servidor (comprova l'URL i el tipus de servidor): {{-error}}",
+ "tr": "Sunucuya ulaşılamadı (URL'yi ve sunucu türünü kontrol edin): {{-error}}",
+ "uk": "Не вдалося підключитися до сервера (перевірте URL-адресу та тип сервера): {{-error}}"
+ },
+ "MCP$TEST_ERROR_STDIO_START": {
+ "en": "Could not start the server command: {{-error}}",
+ "ja": "サーバーのコマンドを起動できませんでした: {{-error}}",
+ "zh-CN": "无法启动服务器命令:{{-error}}",
+ "zh-TW": "無法啟動伺服器命令:{{-error}}",
+ "ko-KR": "서버 명령을 시작할 수 없습니다: {{-error}}",
+ "no": "Kunne ikke starte serverkommandoen: {{-error}}",
+ "ar": "تعذّر تشغيل أمر الخادم: {{-error}}",
+ "de": "Der Serverbefehl konnte nicht gestartet werden: {{-error}}",
+ "fr": "Impossible de démarrer la commande du serveur : {{-error}}",
+ "it": "Impossibile avviare il comando del server: {{-error}}",
+ "pt": "Não foi possível iniciar o comando do servidor: {{-error}}",
+ "es": "No se pudo iniciar el comando del servidor: {{-error}}",
+ "ca": "No s'ha pogut iniciar l'ordre del servidor: {{-error}}",
+ "tr": "Sunucu komutu başlatılamadı: {{-error}}",
+ "uk": "Не вдалося запустити команду сервера: {{-error}}"
},
"MCP$TEST_ERROR_UNKNOWN": {
"en": "Connection failed: {{-error}}",
diff --git a/src/utils/mcp-test-error-message.ts b/src/utils/mcp-test-error-message.ts
index 18e1f15440..ab9e02a469 100644
--- a/src/utils/mcp-test-error-message.ts
+++ b/src/utils/mcp-test-error-message.ts
@@ -1,22 +1,30 @@
import type { TFunction } from "i18next";
import { I18nKey } from "#/i18n/declaration";
-import type { ExtendedMCPTestFailureKind } from "#/types/mcp-server";
+import type {
+ ExtendedMCPTestFailureKind,
+ MCPServerType,
+} from "#/types/mcp-server";
/**
* Kind-specific, localized guidance for a failed MCP connection test.
* `error` is interpolated for the kinds whose message surfaces the provider
- * detail — callers pass display-safe (redacted) text.
+ * detail — callers pass display-safe (redacted) text. `serverType` picks
+ * transport-appropriate copy for a `connection` failure: a stdio server has
+ * no URL, its command failed to start. An unknown type reads as remote.
*/
export function makeMcpTestErrorMessage(
t: TFunction<"openhands">,
errorKind: ExtendedMCPTestFailureKind,
error: string,
+ serverType: MCPServerType | undefined,
): string {
switch (errorKind) {
case "timeout":
return t(I18nKey.MCP$TEST_ERROR_TIMEOUT);
case "connection":
- return t(I18nKey.MCP$TEST_ERROR_CONNECTION);
+ return serverType === "stdio"
+ ? t(I18nKey.MCP$TEST_ERROR_STDIO_START, { error })
+ : t(I18nKey.MCP$TEST_ERROR_CONNECTION, { error });
case "credentials":
return t(I18nKey.MCP$TEST_ERROR_CREDENTIALS, { error });
default: