Skip to content

🙌 OpenHands: AI-Driven Development

feat(frontend): warn when the LLM is not configured after skipping onboarding (#1011)

Hiep Le6c376bdd5757
diff --git a/__tests__/components/home/llm-not-configured-banner.test.tsx b/__tests__/components/home/llm-not-configured-banner.test.tsx
new file mode 100644
index 0000000000..7c9aaf710c
--- /dev/null
+++ b/__tests__/components/home/llm-not-configured-banner.test.tsx
@@ -0,0 +1,188 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { LlmNotConfiguredBanner } from "#/components/features/home/llm-not-configured-banner";
+import { NavigationProvider } from "#/context/navigation-context";
+import { useSettings } from "#/hooks/query/use-settings";
+import { useConfig } from "#/hooks/query/use-config";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import OptionService from "#/api/option-service/option-service.api";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+import { Settings } from "#/types/settings";
+import { WebClientConfig } from "#/api/option-service/option.types";
+
+function buildSettings(overrides: Partial<Settings> = {}): Settings {
+ return {
+ ...MOCK_DEFAULT_USER_SETTINGS,
+ ...overrides,
+ agent_settings:
+ overrides.agent_settings ?? MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+ };
+}
+
+function buildConfig(hideLlmSettings = false): WebClientConfig {
+ return {
+ posthog_client_key: null,
+ feature_flags: {
+ hide_llm_settings: hideLlmSettings,
+ hide_users_page: true,
+ },
+ providers_configured: [],
+ maintenance_start_time: null,
+ recaptcha_site_key: null,
+ faulty_models: [],
+ error_message: null,
+ updated_at: "2026-01-01T00:00:00.000Z",
+ };
+}
+
+// Renders the banner next to a probe that flips on once both underlying
+// queries have resolved. The "hidden" assertions wait on this marker so they
+// observe the settled state rather than the (always-empty) loading frame.
+function ProbedBanner() {
+ const settings = useSettings();
+ const config = useConfig();
+ return (
+ <>
+ <LlmNotConfiguredBanner />
+ {settings.isFetched && config.isFetched ? (
+ <div data-testid="queries-settled" />
+ ) : null}
+ </>
+ );
+}
+
+function renderBanner() {
+ const navigate = vi.fn();
+ const queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+ render(
+ <QueryClientProvider client={queryClient}>
+ <NavigationProvider
+ value={{
+ currentPath: "/",
+ conversationId: null,
+ isNavigating: false,
+ navigate,
+ }}
+ >
+ <ProbedBanner />
+ </NavigationProvider>
+ </QueryClientProvider>,
+ );
+ return { navigate };
+}
+
+describe("LlmNotConfiguredBanner", () => {
+ beforeEach(() => {
+ vi.restoreAllMocks();
+ vi.spyOn(OptionService, "getConfig").mockResolvedValue(buildConfig());
+ });
+
+ it("warns the user when no LLM API key is set (the skip-onboarding case)", async () => {
+ // Arrange: an OpenHands agent with no key — what "Skip for now" leaves.
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+ buildSettings({ llm_api_key_set: false }),
+ );
+
+ // Act
+ renderBanner();
+
+ // Assert
+ expect(
+ await screen.findByTestId("home-llm-not-configured-banner"),
+ ).toBeInTheDocument();
+ });
+
+ it("stays hidden once an LLM API key is configured", async () => {
+ // Arrange
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+ buildSettings({ llm_api_key_set: true }),
+ );
+
+ // Act
+ renderBanner();
+ await screen.findByTestId("queries-settled");
+
+ // Assert
+ expect(
+ screen.queryByTestId("home-llm-not-configured-banner"),
+ ).not.toBeInTheDocument();
+ });
+
+ it("stays hidden for ACP agents, which own their LLM and need no key", async () => {
+ // Arrange: ACP agent, no key — must not be nagged.
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+ buildSettings({
+ llm_api_key_set: false,
+ agent_settings: {
+ ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+ agent_kind: "acp",
+ },
+ }),
+ );
+
+ // Act
+ renderBanner();
+ await screen.findByTestId("queries-settled");
+
+ // Assert
+ expect(
+ screen.queryByTestId("home-llm-not-configured-banner"),
+ ).not.toBeInTheDocument();
+ });
+
+ it("stays hidden when the LLM settings page is hidden by feature flag", async () => {
+ // Arrange: no key, but the settings page is hidden — routing the user to
+ // /settings/llm would dead-end, so the hook treats the LLM as configured.
+ vi.spyOn(OptionService, "getConfig").mockResolvedValue(buildConfig(true));
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+ buildSettings({ llm_api_key_set: false }),
+ );
+
+ // Act
+ renderBanner();
+ await screen.findByTestId("queries-settled");
+
+ // Assert
+ expect(
+ screen.queryByTestId("home-llm-not-configured-banner"),
+ ).not.toBeInTheDocument();
+ });
+
+ it("warns when settings 404 — the genuine new-user state — despite the error flag", async () => {
+ // Arrange: a 404 means no settings exist yet. useSettings maps it to
+ // DEFAULT_SETTINGS (no key) while keeping isError set, so the banner must
+ // still appear — this is the real "Skip for now" state. Guards against
+ // conflating this with a transient fetch error that should suppress it.
+ vi.spyOn(SettingsService, "getSettings").mockRejectedValue({ status: 404 });
+
+ // Act
+ renderBanner();
+
+ // Assert
+ expect(
+ await screen.findByTestId("home-llm-not-configured-banner"),
+ ).toBeInTheDocument();
+ });
+
+ it("routes the user to LLM settings when the action is clicked", async () => {
+ // Arrange
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+ buildSettings({ llm_api_key_set: false }),
+ );
+ const user = userEvent.setup();
+ const { navigate } = renderBanner();
+
+ // Act
+ await user.click(
+ await screen.findByTestId("home-llm-not-configured-action"),
+ );
+
+ // Assert
+ expect(navigate).toHaveBeenCalledWith("/settings/llm");
+ });
+});
diff --git a/src/components/features/home/llm-not-configured-banner.tsx b/src/components/features/home/llm-not-configured-banner.tsx
new file mode 100644
index 0000000000..75634ab3ab
--- /dev/null
+++ b/src/components/features/home/llm-not-configured-banner.tsx
@@ -0,0 +1,53 @@
+import { useTranslation } from "react-i18next";
+import { FaTriangleExclamation } from "react-icons/fa6";
+import { I18nKey } from "#/i18n/declaration";
+import { useNavigation } from "#/context/navigation-context";
+import { useLlmConfigured } from "#/hooks/use-llm-configured";
+import { BrandButton } from "#/components/features/settings/brand-button";
+import { Typography } from "#/ui/typography";
+
+/**
+ * Warns the user on the home screen when the active agent has no usable LLM —
+ * most notably after they skip onboarding, which persists no settings. Offers
+ * a single action that routes to LLM settings so the failure is communicated
+ * up front instead of surfacing only when a conversation attempt errors out.
+ *
+ * Renders nothing while settings load (avoids a flash) or once the LLM is
+ * configured; the settings query refetches after a key is saved, so the banner
+ * unmounts on its own.
+ */
+export function LlmNotConfiguredBanner() {
+ const { t } = useTranslation("openhands");
+ const { navigate } = useNavigation();
+ const { isConfigured, isLoading } = useLlmConfigured();
+
+ if (isLoading || isConfigured) {
+ return null;
+ }
+
+ return (
+ <div
+ data-testid="home-llm-not-configured-banner"
+ role="alert"
+ className="bg-base border border-primary text-white p-4 rounded flex flex-row items-center justify-between gap-3 mt-3"
+ >
+ <div className="flex items-center">
+ <div className="flex-shrink-0">
+ <FaTriangleExclamation className="text-primary align-middle" />
+ </div>
+ <Typography.Text className="ml-3 text-sm font-medium">
+ {t(I18nKey.HOME$LLM_NOT_CONFIGURED_MESSAGE)}
+ </Typography.Text>
+ </div>
+
+ <BrandButton
+ testId="home-llm-not-configured-action"
+ type="button"
+ variant="primary"
+ onClick={() => navigate("/settings/llm")}
+ >
+ {t(I18nKey.HOME$LLM_NOT_CONFIGURED_ACTION)}
+ </BrandButton>
+ </div>
+ );
+}
diff --git a/src/hooks/use-llm-configured.ts b/src/hooks/use-llm-configured.ts
new file mode 100644
index 0000000000..943cd8a68b
--- /dev/null
+++ b/src/hooks/use-llm-configured.ts
@@ -0,0 +1,62 @@
+import { useSettings } from "#/hooks/query/use-settings";
+import { useConfig } from "#/hooks/query/use-config";
+import { isSettingsPageHidden } from "#/utils/settings-utils";
+
+interface LlmConfiguredResult {
+ /**
+ * True when the active backend's agent has a usable LLM:
+ * - ACP agents own their LLM via a subprocess, so they never need a key.
+ * - OpenHands agents are ready only once an LLM API key has been saved.
+ * - When the LLM settings page is hidden by a feature flag there is no
+ * place to finish setup, so we treat the LLM as configured to avoid
+ * surfacing an actionless warning.
+ */
+ isConfigured: boolean;
+ /**
+ * True while the configured/unconfigured state is indeterminate — either
+ * settings/config are still resolving, or a fetch failed and left us with no
+ * data to decide from. Consumers should render nothing in this state so a
+ * warning doesn't flash before data loads or on a transient network error.
+ */
+ isLoading: boolean;
+}
+
+/**
+ * Reports whether the active backend's agent has an LLM ready to run
+ * conversations. Surfaces the gap left by the onboarding "Skip for now" path,
+ * which persists no settings — leaving an OpenHands agent without an API key.
+ */
+export function useLlmConfigured(): LlmConfiguredResult {
+ const {
+ data: settings,
+ isLoading: settingsLoading,
+ isError: settingsError,
+ } = useSettings();
+ const {
+ data: config,
+ isLoading: configLoading,
+ isError: configError,
+ } = useConfig();
+
+ const isAcpAgent = settings?.agent_settings?.agent_kind === "acp";
+ const hasApiKey = settings?.llm_api_key_set === true;
+ const llmSettingsHidden = isSettingsPageHidden(
+ "/settings/llm",
+ config?.feature_flags,
+ );
+
+ // Treat a fetch failure as indeterminate (same as loading) only when it
+ // leaves us with no data to decide from — otherwise a transient network
+ // error would surface the banner with the same urgency as a genuinely
+ // missing API key. A settings 404 is deliberately not covered here:
+ // `useSettings` maps it to DEFAULT_SETTINGS (no key, OpenHands agent) while
+ // keeping `isError` set, and that is exactly the new-user / "Skip for now"
+ // state the banner exists to catch — so we keep deciding from that data.
+ const settingsIndeterminate = settingsLoading || (settingsError && !settings);
+ const configIndeterminate = configLoading || (configError && !config);
+
+ return {
+ isConfigured: isAcpAgent || hasApiKey || llmSettingsHidden,
+ isLoading: settingsIndeterminate || configIndeterminate,
+ };
+}
diff --git a/src/i18n/translation.json b/src/i18n/translation.json
index 81f7e37ee5..a914dee718 100644
--- a/src/i18n/translation.json
+++ b/src/i18n/translation.json
@@ -611,6 +611,40 @@
"uk": "Почати з нуля",
"ca": "Comença des de zero"
},
+ "HOME$LLM_NOT_CONFIGURED_MESSAGE": {
+ "en": "Your LLM isn't set up yet, so conversations won't run. Finish setup to get started.",
+ "ja": "LLMがまだ設定されていないため、会話を実行できません。セットアップを完了して始めましょう。",
+ "zh-CN": "您的 LLM 尚未设置,因此无法进行对话。请完成设置以开始使用。",
+ "zh-TW": "您的 LLM 尚未設定,因此無法進行對話。請完成設定以開始使用。",
+ "ko-KR": "LLM이 아직 설정되지 않아 대화를 실행할 수 없습니다. 설정을 완료하여 시작하세요.",
+ "no": "LLM-en din er ikke satt opp ennå, så samtaler vil ikke kjøre. Fullfør oppsettet for å komme i gang.",
+ "it": "Il tuo LLM non è ancora configurato, quindi le conversazioni non funzioneranno. Completa la configurazione per iniziare.",
+ "pt": "Seu LLM ainda não está configurado, então as conversas não funcionarão. Conclua a configuração para começar.",
+ "es": "Tu LLM aún no está configurado, por lo que las conversaciones no funcionarán. Completa la configuración para empezar.",
+ "ar": "لم يتم إعداد نموذج اللغة الخاص بك بعد، لذا لن تعمل المحادثات. أكمل الإعداد للبدء.",
+ "fr": "Votre LLM n'est pas encore configuré, les conversations ne fonctionneront donc pas. Terminez la configuration pour commencer.",
+ "tr": "LLM'niz henüz ayarlanmadı, bu yüzden konuşmalar çalışmaz. Başlamak için kurulumu tamamlayın.",
+ "de": "Dein LLM ist noch nicht eingerichtet, daher können keine Konversationen ausgeführt werden. Schließe die Einrichtung ab, um loszulegen.",
+ "uk": "Ваш LLM ще не налаштований, тому розмови не працюватимуть. Завершіть налаштування, щоб почати.",
+ "ca": "El teu LLM encara no està configurat, així que les converses no funcionaran. Completa la configuració per començar."
+ },
+ "HOME$LLM_NOT_CONFIGURED_ACTION": {
+ "en": "Set up LLM",
+ "ja": "LLMを設定",
+ "zh-CN": "设置 LLM",
+ "zh-TW": "設定 LLM",
+ "ko-KR": "LLM 설정",
+ "no": "Sett opp LLM",
+ "it": "Configura LLM",
+ "pt": "Configurar LLM",
+ "es": "Configurar LLM",
+ "ar": "إعداد نموذج اللغة",
+ "fr": "Configurer le LLM",
+ "tr": "LLM'yi ayarla",
+ "de": "LLM einrichten",
+ "uk": "Налаштувати LLM",
+ "ca": "Configura el LLM"
+ },
"HOME$READ_THIS": {
"en": "Read this",
"ja": "詳細はこちら",
diff --git a/src/routes/home.tsx b/src/routes/home.tsx
index 46a5db6478..84578dde6b 100644
--- a/src/routes/home.tsx
+++ b/src/routes/home.tsx
@@ -1,5 +1,6 @@
import { PrefetchPageLinks } from "react-router";
import { HomeChatLauncher } from "#/components/features/home/home-chat-launcher";
+import { LlmNotConfiguredBanner } from "#/components/features/home/llm-not-configured-banner";
import { OnboardingHost } from "#/components/features/onboarding";
<PrefetchPageLinks page="/conversations/:conversationId" />;
@@ -10,6 +11,8 @@ function HomeScreen() {
data-testid="home-screen"
className="custom-scrollbar-always flex h-full flex-col overflow-y-auto rounded-xl bg-transparent px-4 md:px-0 lg:px-[42px]"
>
+ <LlmNotConfiguredBanner />
+
<div className="flex flex-1 min-h-0 flex-col items-center justify-center">
<HomeChatLauncher />
</div>