Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python

fix: provide real error for onboarding apiKey setup and settings (#2152)

Wallgaud8b65613c976
diff --git a/frontend/app/api/mutations/useOnboardingMutation.ts b/frontend/app/api/mutations/useOnboardingMutation.ts
index a174d8ef4..a21b5ca0f 100644
--- a/frontend/app/api/mutations/useOnboardingMutation.ts
+++ b/frontend/app/api/mutations/useOnboardingMutation.ts
@@ -3,6 +3,7 @@ import {
useMutation,
useQueryClient,
} from "@tanstack/react-query";
+import { formatProviderErrorMessage } from "@/lib/chat-stream-errors";
import { useUpdateOnboardingStateMutation } from "./useUpdateOnboardingStateMutation";
export interface OnboardingVariables {
@@ -42,8 +43,12 @@ async function submitOnboarding(
});
if (!response.ok) {
- const error = await response.json();
- throw new Error(error.error || "Failed to complete onboarding");
+ const error = await response.json().catch(() => ({}));
+ const raw =
+ error && typeof error === "object" && typeof error.error === "string"
+ ? error.error
+ : "Failed to complete onboarding";
+ throw new Error(formatProviderErrorMessage(raw));
}
return response.json();
diff --git a/frontend/app/api/mutations/useUpdateSettingsMutation.ts b/frontend/app/api/mutations/useUpdateSettingsMutation.ts
index 8744bfc54..7c9981390 100644
--- a/frontend/app/api/mutations/useUpdateSettingsMutation.ts
+++ b/frontend/app/api/mutations/useUpdateSettingsMutation.ts
@@ -3,6 +3,7 @@ import {
useMutation,
useQueryClient,
} from "@tanstack/react-query";
+import { formatProviderErrorMessage } from "@/lib/chat-stream-errors";
import { useGetCurrentProviderModelsQuery } from "../queries/useGetModelsQuery";
import type { Settings } from "../queries/useGetSettingsQuery";
@@ -69,9 +70,9 @@ class UpdateSettingsError extends Error {
readonly affectedModels?: AffectedEmbeddingModel[];
constructor(status: number, data: Record<string, unknown>) {
- const message =
+ const raw =
typeof data.error === "string" ? data.error : "Failed to update settings";
- super(message);
+ super(formatProviderErrorMessage(raw));
this.name = "UpdateSettingsError";
this.status = status;
this.code = typeof data.code === "string" ? data.code : undefined;
diff --git a/frontend/app/api/queries/useGetModelsQuery.ts b/frontend/app/api/queries/useGetModelsQuery.ts
index dfe92be37..9c1360302 100644
--- a/frontend/app/api/queries/useGetModelsQuery.ts
+++ b/frontend/app/api/queries/useGetModelsQuery.ts
@@ -3,6 +3,7 @@ import {
useQuery,
useQueryClient,
} from "@tanstack/react-query";
+import { formatProviderErrorMessage } from "@/lib/chat-stream-errors";
import { useGetSettingsQuery } from "./useGetSettingsQuery";
export interface ModelOption {
@@ -19,10 +20,14 @@ export interface ModelsResponse {
export interface OpenAIModelsParams {
apiKey?: string;
+ /** When true, omit api_key so the backend uses configured/env credentials. */
+ useEnvKey?: boolean;
}
export interface AnthropicModelsParams {
apiKey?: string;
+ /** When true, omit api_key so the backend uses configured/env credentials. */
+ useEnvKey?: boolean;
}
export interface OllamaModelsParams {
@@ -33,6 +38,20 @@ export interface IBMModelsParams {
endpoint?: string;
apiKey?: string;
projectId?: string;
+ /** When true, omit api_key so the backend uses configured/env credentials. */
+ useEnvKey?: boolean;
+}
+
+async function throwModelsFetchError(
+ response: Response,
+ fallback: string,
+): Promise<never> {
+ const data = await response.json().catch(() => ({}));
+ const raw =
+ data && typeof data === "object" && typeof data.error === "string"
+ ? data.error
+ : fallback;
+ throw new Error(formatProviderErrorMessage(raw));
}
export const useGetOpenAIModelsQuery = (
@@ -40,34 +59,30 @@ export const useGetOpenAIModelsQuery = (
options?: Omit<UseQueryOptions<ModelsResponse>, "queryKey" | "queryFn">,
) => {
const queryClient = useQueryClient();
-
- async function getOpenAIModels(): Promise<ModelsResponse> {
- const url = new URL("/api/models/openai", window.location.origin);
- const body: { api_key?: string } = {};
- if (params?.apiKey) {
- body.api_key = params.apiKey;
- }
-
- const response = await fetch(url.toString(), {
- method: "POST",
- headers: {
- "Content-Type": "application/json",
- },
- body: JSON.stringify(body),
- });
- if (response.ok) {
- return await response.json();
- } else {
- throw new Error("Failed to fetch OpenAI models");
- }
- }
+ const useEnvKey = !!params?.useEnvKey;
+ const apiKey = useEnvKey ? "" : params?.apiKey || "";
return useQuery(
{
- queryKey: ["models", "openai", params],
- queryFn: getOpenAIModels,
- staleTime: 0, // Always fetch fresh data
- gcTime: 0, // Don't cache results
+ queryKey: ["models", "openai", useEnvKey, apiKey] as const,
+ queryFn: async (): Promise<ModelsResponse> => {
+ const body: { api_key?: string } = {};
+ if (!useEnvKey && apiKey) {
+ body.api_key = apiKey;
+ }
+
+ const response = await fetch("/api/models/openai", {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify(body),
+ });
+ if (response.ok) {
+ return (await response.json()) as ModelsResponse;
+ }
+ return throwModelsFetchError(response, "Failed to fetch OpenAI models");
+ },
+ staleTime: 0,
+ gcTime: 0,
retry: false,
...options,
},
@@ -80,34 +95,33 @@ export const useGetAnthropicModelsQuery = (
options?: Omit<UseQueryOptions<ModelsResponse>, "queryKey" | "queryFn">,
) => {
const queryClient = useQueryClient();
-
- async function getAnthropicModels(): Promise<ModelsResponse> {
- const url = new URL("/api/models/anthropic", window.location.origin);
- const body: { api_key?: string } = {};
- if (params?.apiKey) {
- body.api_key = params.apiKey;
- }
-
- const response = await fetch(url.toString(), {
- method: "POST",
- headers: {
- "Content-Type": "application/json",
- },
- body: JSON.stringify(body),
- });
- if (response.ok) {
- return await response.json();
- } else {
- throw new Error("Failed to fetch Anthropic models");
- }
- }
+ const useEnvKey = !!params?.useEnvKey;
+ const apiKey = useEnvKey ? "" : params?.apiKey || "";
return useQuery(
{
- queryKey: ["models", "anthropic", params],
- queryFn: getAnthropicModels,
- staleTime: 0, // Always fetch fresh data
- gcTime: 0, // Don't cache results
+ queryKey: ["models", "anthropic", useEnvKey, apiKey] as const,
+ queryFn: async (): Promise<ModelsResponse> => {
+ const body: { api_key?: string } = {};
+ if (!useEnvKey && apiKey) {
+ body.api_key = apiKey;
+ }
+
+ const response = await fetch("/api/models/anthropic", {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify(body),
+ });
+ if (response.ok) {
+ return (await response.json()) as ModelsResponse;
+ }
+ return throwModelsFetchError(
+ response,
+ "Failed to fetch Anthropic models",
+ );
+ },
+ staleTime: 0,
+ gcTime: 0,
retry: false,
...options,
},
@@ -120,27 +134,25 @@ export const useGetOllamaModelsQuery = (
options?: Omit<UseQueryOptions<ModelsResponse>, "queryKey" | "queryFn">,
) => {
const queryClient = useQueryClient();
-
- async function getOllamaModels(): Promise<ModelsResponse> {
- const url = new URL("/api/models/ollama", window.location.origin);
- if (params?.endpoint) {
- url.searchParams.set("endpoint", params.endpoint);
- }
-
- const response = await fetch(url.toString());
- if (response.ok) {
- return await response.json();
- } else {
- throw new Error("Failed to fetch Ollama models");
- }
- }
+ const endpoint = params?.endpoint || "";
return useQuery(
{
- queryKey: ["models", "ollama", params],
- queryFn: getOllamaModels,
- staleTime: 0, // Always fetch fresh data
- gcTime: 0, // Don't cache results
+ queryKey: ["models", "ollama", endpoint] as const,
+ queryFn: async (): Promise<ModelsResponse> => {
+ const url = new URL("/api/models/ollama", window.location.origin);
+ if (endpoint) {
+ url.searchParams.set("endpoint", endpoint);
+ }
+
+ const response = await fetch(url.toString());
+ if (response.ok) {
+ return (await response.json()) as ModelsResponse;
+ }
+ return throwModelsFetchError(response, "Failed to fetch Ollama models");
+ },
+ staleTime: 0,
+ gcTime: 0,
retry: false,
...options,
},
@@ -153,44 +165,49 @@ export const useGetIBMModelsQuery = (
options?: Omit<UseQueryOptions<ModelsResponse>, "queryKey" | "queryFn">,
) => {
const queryClient = useQueryClient();
-
- async function getIBMModels(): Promise<ModelsResponse> {
- const url = new URL("/api/models/ibm", window.location.origin);
- const body: {
- endpoint?: string;
- api_key?: string;
- project_id?: string;
- } = {};
- if (params?.endpoint) {
- body.endpoint = params.endpoint;
- }
- if (params?.apiKey) {
- body.api_key = params.apiKey;
- }
- if (params?.projectId) {
- body.project_id = params.projectId;
- }
-
- const response = await fetch(url.toString(), {
- method: "POST",
- headers: {
- "Content-Type": "application/json",
- },
- body: JSON.stringify(body),
- });
- if (response.ok) {
- return await response.json();
- } else {
- throw new Error("Failed to fetch IBM models");
- }
- }
+ const useEnvKey = !!params?.useEnvKey;
+ const endpoint = params?.endpoint || "";
+ const projectId = params?.projectId || "";
+ const apiKey = useEnvKey ? "" : params?.apiKey || "";
return useQuery(
{
- queryKey: ["models", "ibm", params],
- queryFn: getIBMModels,
- staleTime: 0, // Always fetch fresh data
- gcTime: 0, // Don't cache results
+ queryKey: [
+ "models",
+ "ibm",
+ useEnvKey,
+ endpoint,
+ projectId,
+ apiKey,
+ ] as const,
+ queryFn: async (): Promise<ModelsResponse> => {
+ const body: {
+ endpoint?: string;
+ api_key?: string;
+ project_id?: string;
+ } = {};
+ if (endpoint) {
+ body.endpoint = endpoint;
+ }
+ if (projectId) {
+ body.project_id = projectId;
+ }
+ if (!useEnvKey && apiKey) {
+ body.api_key = apiKey;
+ }
+
+ const response = await fetch("/api/models/ibm", {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify(body),
+ });
+ if (response.ok) {
+ return (await response.json()) as ModelsResponse;
+ }
+ return throwModelsFetchError(response, "Failed to fetch IBM models");
+ },
+ staleTime: 0,
+ gcTime: 0,
retry: false,
...options,
},
@@ -208,9 +225,8 @@ export const useGetCurrentProviderModelsQuery = (
const { data: settings } = useGetSettingsQuery();
const currentProvider = settings?.agent?.llm_provider;
- // Determine which hook to use based on current provider
const openaiModels = useGetOpenAIModelsQuery(
- { apiKey: "" },
+ { useEnvKey: true },
{
enabled: currentProvider === "openai" && options?.enabled !== false,
...options,
@@ -218,7 +234,7 @@ export const useGetCurrentProviderModelsQuery = (
);
const anthropicModels = useGetAnthropicModelsQuery(
- { apiKey: "" },
+ { useEnvKey: true },
{
enabled: currentProvider === "anthropic" && options?.enabled !== false,
...options,
@@ -239,8 +255,8 @@ export const useGetCurrentProviderModelsQuery = (
const ibmModels = useGetIBMModelsQuery(
{
endpoint: settings?.providers?.watsonx?.endpoint,
- apiKey: "",
projectId: settings?.providers?.watsonx?.project_id,
+ useEnvKey: true,
},
{
enabled:
@@ -252,7 +268,6 @@ export const useGetCurrentProviderModelsQuery = (
},
);
- // Return the appropriate query result based on current provider
switch (currentProvider) {
case "openai":
return openaiModels;
@@ -263,12 +278,6 @@ export const useGetCurrentProviderModelsQuery = (
case "watsonx":
return ibmModels;
default:
- // Return a default/disabled query if no provider is set
- return {
- data: undefined,
- isLoading: false,
- error: null,
- refetch: async () => ({ data: undefined }),
- } as ReturnType<typeof useGetOpenAIModelsQuery>;
+ return openaiModels;
}
};
diff --git a/frontend/app/api/queries/useProviderHealthQuery.ts b/frontend/app/api/queries/useProviderHealthQuery.ts
index a1b1432d1..885bd2ef5 100644
--- a/frontend/app/api/queries/useProviderHealthQuery.ts
+++ b/frontend/app/api/queries/useProviderHealthQuery.ts
@@ -66,13 +66,12 @@ export const useProviderHealthQuery = (
try {
const url = new URL("/api/provider/health", window.location.origin);
- // Add provider query param if specified
if (params?.provider) {
url.searchParams.set("provider", params.provider);
}
- // Add test_completion query param if specified or if chat error exists
- // Use the same testCompletion value that's in the queryKey
+ // After chat/ingest failure, run a completion check so the banner shows
+ // the real cause (disabled key vs missing model). Otherwise lightweight.
const testCompletion = params?.test_completion ?? hasChatError;
if (testCompletion) {
url.searchParams.set("test_completion", "true");
@@ -81,9 +80,12 @@ export const useProviderHealthQuery = (
const response = await fetch(url.toString());
if (response.ok) {
- return await response.json();
+ const data = (await response.json()) as ProviderHealthResponse;
+ if (hasChatError) {
+ setChatError(false);
+ }
+ return data;
} else if (response.status === 503) {
- // Backend is up but provider validation failed
const errorData = await response.json().catch(() => ({}));
return {
status: "unhealthy",
@@ -96,7 +98,6 @@ export const useProviderHealthQuery = (
details: errorData.details,
};
} else {
- // Other backend errors (400, etc.) - treat as provider issues
const errorData = await response.json().catch(() => ({}));
return {
status: "error",
@@ -110,7 +111,6 @@ export const useProviderHealthQuery = (
};
}
} catch (error) {
- // Network error - backend is likely down, don't show provider banner
return {
status: "backend-unavailable",
message: error instanceof Error ? error.message : "Connection failed",
@@ -119,8 +119,7 @@ export const useProviderHealthQuery = (
}
}
- // Include hasChatError in queryKey so React Query refetches when it changes
- // This ensures the health check runs with test_completion=true when chat errors occur
+ // hasChatError in the key forces an immediate refetch when chat/ingest fails.
const testCompletion = params?.test_completion ?? hasChatError;
const queryKey = ["provider", "health", testCompletion, hasChatError];
const failureCountKey = queryKey.join("-");
@@ -129,47 +128,42 @@ export const useProviderHealthQuery = (
{
queryKey,
queryFn: checkProviderHealth,
- retry: false, // Don't retry health checks automatically
+ retry: false,
refetchInterval: (query) => {
const data = query.state.data;
const status = data?.status;
- // If healthy, reset failure count and check every 30 seconds
- // Also reset chat error flag if we're using test_completion=true and it succeeded
if (status === "healthy") {
failureCountMap.set(failureCountKey, 0);
- // If we were checking with test_completion=true due to chat errors, reset the flag
- if (hasChatError && setChatError) {
- setChatError(false);
- }
return 30000;
}
- // If backend unavailable, use moderate polling
if (status === "backend-unavailable") {
return 15000;
}
- // For unhealthy/error status, use exponential backoff
+ // Keep probing while latched so fixing the real cause updates the banner
+ // within seconds (key re-enable or model change).
+ if (hasChatError) {
+ return 5000;
+ }
+
const currentFailures = failureCountMap.get(failureCountKey) || 0;
failureCountMap.set(failureCountKey, currentFailures + 1);
-
- // Exponential backoff: 5s, 10s, 20s, then 30s
const backoffDelays = [5000, 10000, 20000, 30000];
- const delay =
- backoffDelays[Math.min(currentFailures, backoffDelays.length - 1)];
-
- return delay;
+ return backoffDelays[
+ Math.min(currentFailures, backoffDelays.length - 1)
+ ];
},
- refetchOnWindowFocus: false, // Disabled to reduce unnecessary calls on tab switches
+ refetchOnWindowFocus: false,
refetchOnMount: true,
- staleTime: 30000, // Consider data stale after 30 seconds
+ staleTime: 30000,
enabled:
!!settings?.edited &&
isOnboardingComplete &&
- !hasActiveIngestion && // Disable health checks when ingestion is happening
- providerHealthAllowed && // Admin-only under enforced RBAC
- options?.enabled !== false, // Only run after onboarding is complete
+ !hasActiveIngestion &&
+ providerHealthAllowed &&
+ options?.enabled !== false,
...options,
},
queryClient,
diff --git a/frontend/app/chat/page.tsx b/frontend/app/chat/page.tsx
index 759382c6b..0a6f8d9b1 100644
--- a/frontend/app/chat/page.tsx
+++ b/frontend/app/chat/page.tsx
@@ -142,6 +142,8 @@ function ChatPage() {
});
if (message.error) {
+ // Latch banner deep-probe so it shows the same provider/model error.
+ setChatError(true);
// Sidebar id stays on currentConversationId; onError clears Langflow chaining.
if (responseId) {
liveErrorConversationRef.current = responseId;
@@ -161,6 +163,9 @@ function ChatPage() {
return;
}
+ // Successful turn — drop the banner deep-probe latch.
+ setChatError(false);
+
trackLLMCall({
mode: "chat",
model: settings?.agent?.llm_model,
@@ -725,6 +730,7 @@ function ChatPage() {
usage: result.usage,
};
setMessages((prev) => [...prev, assistantMessage]);
+ setChatError(false);
if (result.response_id) {
cancelNudges();
}
diff --git a/frontend/app/onboarding/_components/anthropic-onboarding.tsx b/frontend/app/onboarding/_components/anthropic-onboarding.tsx
index 2deaae475..8d385d3b0 100644
--- a/frontend/app/onboarding/_components/anthropic-onboarding.tsx
+++ b/frontend/app/onboarding/_components/anthropic-onboarding.tsx
@@ -1,5 +1,5 @@
import type { Dispatch, SetStateAction } from "react";
-import { useEffect, useState } from "react";
+import { useState } from "react";
import AnthropicLogo from "@/components/icons/anthropic-logo";
import { LabelInput } from "@/components/label-input";
import { LabelWrapper } from "@/components/label-wrapper";
@@ -18,12 +18,10 @@ import { AdvancedOnboarding } from "./advanced";
export function AnthropicOnboarding({
setSettings,
- setIsLoadingModels,
isEmbedding = false,
hasEnvApiKey = false,
}: {
setSettings: Dispatch<SetStateAction<OnboardingVariables>>;
- setIsLoadingModels?: (isLoading: boolean) => void;
isEmbedding?: boolean;
hasEnvApiKey?: boolean;
}) {
@@ -40,20 +38,23 @@ export function AnthropicOnboarding({
}
const debouncedApiKey = useDebouncedValue(apiKey, 500);
- // Fetch models from API when API key is provided
const {
data: modelsData,
isLoading: isLoadingModels,
+ isFetching: isFetchingModels,
error: modelsError,
} = useGetAnthropicModelsQuery(
getFromEnv
- ? { apiKey: "" }
+ ? { useEnvKey: true }
: debouncedApiKey
- ? { apiKey: debouncedApiKey }
+ ? { apiKey: debouncedApiKey, useEnvKey: false }
: undefined,
{ enabled: debouncedApiKey !== "" || getFromEnv },
);
- // Use custom hook for model selection logic
+
+ const showModelsError =
+ !!modelsError && !isLoadingModels && !isFetchingModels;
+
const {
languageModel,
embeddingModel,
@@ -76,15 +77,11 @@ export function AnthropicOnboarding({
setLanguageModel?.("");
};
- useEffect(() => {
- setIsLoadingModels?.(isLoadingModels);
- }, [isLoadingModels, setIsLoadingModels]);
-
- // Update settings when values change
useUpdateSettings(
"anthropic",
{
- apiKey,
+ apiKey: getFromEnv ? undefined : apiKey,
+ clearApiKey: getFromEnv,
languageModel,
embeddingModel,
},
@@ -124,7 +121,7 @@ export function AnthropicOnboarding({
<LabelInput
label="Anthropic API key"
helperText="The API key for your Anthropic account."
- className={modelsError ? "!border-destructive" : ""}
+ className={showModelsError ? "!border-destructive" : ""}
id="api-key"
type="password"
required
@@ -132,15 +129,13 @@ export function AnthropicOnboarding({
value={apiKey}
onChange={(e) => setApiKey(e.target.value)}
/>
- {isLoadingModels && (
+ {(isLoadingModels || isFetchingModels) && (
<p className="text-mmd text-muted-foreground">
Validating API key...
</p>
)}
- {modelsError && (
- <p className="text-mmd text-destructive">
- Invalid Anthropic API key. Verify or replace the key.
- </p>
+ {showModelsError && (
+ <p className="text-mmd text-destructive">{modelsError.message}</p>
)}
</div>
)}
diff --git a/frontend/app/onboarding/_components/ibm-onboarding.tsx b/frontend/app/onboarding/_components/ibm-onboarding.tsx
index cd28e4070..5df710045 100644
--- a/frontend/app/onboarding/_components/ibm-onboarding.tsx
+++ b/frontend/app/onboarding/_components/ibm-onboarding.tsx
@@ -1,5 +1,5 @@
import type { Dispatch, SetStateAction } from "react";
-import { useEffect, useState } from "react";
+import { useState } from "react";
import IBMLogo from "@/components/icons/ibm-logo";
import { LabelInput } from "@/components/label-input";
import { LabelWrapper } from "@/components/label-wrapper";
@@ -20,7 +20,6 @@ import { ModelSelector } from "./model-selector";
export function IBMOnboarding({
isEmbedding = false,
setSettings,
- setIsLoadingModels,
alreadyConfigured = false,
existingEndpoint,
existingProjectId,
@@ -28,7 +27,6 @@ export function IBMOnboarding({
}: {
isEmbedding?: boolean;
setSettings: Dispatch<SetStateAction<OnboardingVariables>>;
- setIsLoadingModels?: (isLoading: boolean) => void;
alreadyConfigured?: boolean;
existingEndpoint?: string;
existingProjectId?: string;
@@ -83,26 +81,34 @@ export function IBMOnboarding({
const debouncedApiKey = useDebouncedValue(apiKey, 500);
const debouncedProjectId = useDebouncedValue(projectId, 500);
- // Fetch models from API when all credentials are provided
const {
data: modelsData,
isLoading: isLoadingModels,
+ isFetching: isFetchingModels,
error: modelsError,
} = useGetIBMModelsQuery(
{
- endpoint: debouncedEndpoint ? debouncedEndpoint : undefined,
- apiKey: getFromEnv ? "" : debouncedApiKey ? debouncedApiKey : undefined,
- projectId: debouncedProjectId ? debouncedProjectId : undefined,
+ endpoint: getFromEnv
+ ? existingEndpoint || debouncedEndpoint || undefined
+ : debouncedEndpoint || undefined,
+ apiKey: getFromEnv ? undefined : debouncedApiKey || undefined,
+ projectId: getFromEnv
+ ? existingProjectId || debouncedProjectId || undefined
+ : debouncedProjectId || undefined,
+ useEnvKey: getFromEnv,
},
{
- enabled:
- (!!debouncedEndpoint && !!debouncedApiKey && !!debouncedProjectId) ||
- getFromEnv ||
- alreadyConfigured,
+ enabled: getFromEnv
+ ? !!(existingEndpoint || debouncedEndpoint) &&
+ !!(existingProjectId || debouncedProjectId)
+ : (!!debouncedEndpoint && !!debouncedApiKey && !!debouncedProjectId) ||
+ alreadyConfigured,
},
);
- // Use custom hook for model selection logic
+ const showModelsError =
+ !!modelsError && !isLoadingModels && !isFetchingModels;
+
const {
languageModel,
embeddingModel,
@@ -116,22 +122,22 @@ export function IBMOnboarding({
setGetFromEnv(fromEnv);
if (fromEnv) {
setApiKey("");
+ setEndpoint(existingEndpoint || "https://us-south.ml.cloud.ibm.com");
+ setProjectId(existingProjectId || "");
}
setEmbeddingModel?.("");
setLanguageModel?.("");
};
- useEffect(() => {
- setIsLoadingModels?.(isLoadingModels);
- }, [isLoadingModels, setIsLoadingModels]);
-
- // Update settings when values change
useUpdateSettings(
"watsonx",
{
- endpoint,
- apiKey,
- projectId,
+ endpoint: getFromEnv
+ ? existingEndpoint || "https://us-south.ml.cloud.ibm.com"
+ : endpoint,
+ apiKey: getFromEnv || alreadyConfigured ? undefined : apiKey,
+ clearApiKey: getFromEnv,
+ projectId: getFromEnv ? existingProjectId || "" : projectId,
languageModel,
embeddingModel,
},
@@ -153,7 +159,10 @@ export function IBMOnboarding({
options={alreadyConfigured ? [] : options}
value={endpoint}
custom
- onValueChange={alreadyConfigured ? () => {} : setEndpoint}
+ onValueChange={
+ alreadyConfigured || getFromEnv ? () => {} : setEndpoint
+ }
+ disabled={alreadyConfigured || getFromEnv}
searchPlaceholder="Search endpoint..."
noOptionsPlaceholder={
alreadyConfigured
@@ -167,6 +176,11 @@ export function IBMOnboarding({
Reusing endpoint from model provider selection.
</p>
)}
+ {getFromEnv && !alreadyConfigured && (
+ <p className="text-mmd text-muted-foreground">
+ Reusing endpoint from environment config.
+ </p>
+ )}
</div>
</LabelWrapper>
@@ -181,13 +195,18 @@ export function IBMOnboarding({
}
value={projectId}
onChange={(e) => setProjectId(e.target.value)}
- disabled={alreadyConfigured}
+ disabled={alreadyConfigured || getFromEnv}
/>
{alreadyConfigured && (
<p className="text-mmd text-muted-foreground">
Reusing project ID from model provider selection.
</p>
)}
+ {getFromEnv && !alreadyConfigured && (
+ <p className="text-mmd text-muted-foreground">
+ Reusing project ID from environment config.
+ </p>
+ )}
</div>
<LabelWrapper
label="Use environment watsonx API key"
@@ -218,7 +237,7 @@ export function IBMOnboarding({
<LabelInput
label="watsonx API key"
helperText="API key to access watsonx.ai"
- className={modelsError ? "!border-destructive" : ""}
+ className={showModelsError ? "!border-destructive" : ""}
id="api-key"
type="password"
required
@@ -226,15 +245,13 @@ export function IBMOnboarding({
value={apiKey}
onChange={(e) => setApiKey(e.target.value)}
/>
- {isLoadingModels && (
+ {(isLoadingModels || isFetchingModels) && (
<p className="text-mmd text-muted-foreground">
Validating API key...
</p>
)}
- {modelsError && (
- <p className="text-mmd text-destructive">
- Invalid watsonx API key. Verify or replace the key.
- </p>
+ {showModelsError && (
+ <p className="text-mmd text-destructive">{modelsError.message}</p>
)}
</div>
)}
@@ -256,14 +273,14 @@ export function IBMOnboarding({
</p>
</div>
)}
- {getFromEnv && isLoadingModels && (
+ {getFromEnv && (isLoadingModels || isFetchingModels) && (
<p className="text-mmd text-muted-foreground">
Validating configuration...
</p>
)}
- {getFromEnv && modelsError && (
+ {getFromEnv && showModelsError && (
<p className="text-mmd text-accent-amber-foreground">
- Connection failed. Check your configuration.
+ {modelsError.message}
</p>
)}
</div>
diff --git a/frontend/app/onboarding/_components/ollama-onboarding.tsx b/frontend/app/onboarding/_components/ollama-onboarding.tsx
index d2f55f472..1c0c72f38 100644
--- a/frontend/app/onboarding/_components/ollama-onboarding.tsx
+++ b/frontend/app/onboarding/_components/ollama-onboarding.tsx
@@ -12,13 +12,11 @@ import { ModelSelector } from "./model-selector";
export function OllamaOnboarding({
setSettings,
- setIsLoadingModels,
isEmbedding = false,
alreadyConfigured = false,
existingEndpoint,
}: {
setSettings: Dispatch<SetStateAction<OnboardingVariables>>;
- setIsLoadingModels?: (isLoading: boolean) => void;
isEmbedding?: boolean;
alreadyConfigured?: boolean;
existingEndpoint?: string;
@@ -28,7 +26,8 @@ export function OllamaOnboarding({
? undefined
: existingEndpoint || `http://localhost:11434`,
);
- const [showConnecting, setShowConnecting] = useState(false);
+ const [connectingVisibleAfterDelay, setConnectingVisibleAfterDelay] =
+ useState(false);
const debouncedEndpoint = useDebouncedValue(endpoint, 500);
// Fetch models from API when endpoint is provided (debounced)
@@ -51,26 +50,24 @@ export function OllamaOnboarding({
embeddingModels,
} = useModelSelection(modelsData, isEmbedding);
- // Handle delayed display of connecting state
- useEffect(() => {
- let timeoutId: NodeJS.Timeout;
+ const isConnecting = !!debouncedEndpoint && isLoadingModels;
- if (debouncedEndpoint && isLoadingModels) {
- timeoutId = setTimeout(() => {
- setIsLoadingModels?.(true);
- setShowConnecting(true);
- }, 500);
- } else {
- setShowConnecting(false);
- setIsLoadingModels?.(false);
+ // Delay "connecting" message to avoid flicker on short fetches.
+ // Visibility is derived from isConnecting so we don't sync false via an effect.
+ useEffect(() => {
+ if (!isConnecting) {
+ return;
}
-
+ const timeoutId = setTimeout(() => {
+ setConnectingVisibleAfterDelay(true);
+ }, 500);
return () => {
- if (timeoutId) {
- clearTimeout(timeoutId);
- }
+ clearTimeout(timeoutId);
+ setConnectingVisibleAfterDelay(false);
};
- }, [debouncedEndpoint, isLoadingModels, setIsLoadingModels]);
+ }, [isConnecting]);
+
+ const showConnecting = isConnecting && connectingVisibleAfterDelay;
// Update settings when values change
useUpdateSettings(
@@ -120,8 +117,7 @@ export function OllamaOnboarding({
)}
{hasConnectionError && (
<p className="text-mmd text-accent-amber-foreground">
- Can&apos;t reach Ollama at {debouncedEndpoint}. Update the base URL
- or start the server.
+ {modelsError.message}
</p>
)}
{hasNoModels && (
diff --git a/frontend/app/onboarding/_components/onboarding-card.tsx b/frontend/app/onboarding/_components/onboarding-card.tsx
index 3b3c32aed..67cb08904 100644
--- a/frontend/app/onboarding/_components/onboarding-card.tsx
+++ b/frontend/app/onboarding/_components/onboarding-card.tsx
@@ -1,9 +1,9 @@
"use client";
-import { useQueryClient } from "@tanstack/react-query";
+import { useIsFetching, useQueryClient } from "@tanstack/react-query";
import { AnimatePresence, motion } from "framer-motion";
import { X } from "lucide-react";
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useEffectEvent, useRef, useState } from "react";
import { toast } from "sonner";
import {
type OnboardingVariables,
@@ -39,6 +39,7 @@ import {
trackProcessFailure,
trackProcessSuccess,
} from "@/lib/analytics";
+import { formatProviderErrorMessage } from "@/lib/chat-stream-errors";
import { cn } from "@/lib/utils";
import { AnimatedProviderSteps } from "./animated-provider-steps";
import { AnthropicOnboarding } from "./anthropic-onboarding";
@@ -51,8 +52,6 @@ interface OnboardingCardProps {
onComplete: () => void;
isCompleted?: boolean;
isEmbedding?: boolean;
- setIsLoadingModels?: (isLoading: boolean) => void;
- setLoadingStatus?: (status: string[]) => void;
}
const STEP_LIST = [
@@ -80,7 +79,8 @@ const OnboardingCard = ({
isEmbedding ? "openai" : "anthropic",
);
- const [isLoadingModels, setIsLoadingModels] = useState<boolean>(false);
+ // Read model-fetch loading from React Query instead of syncing it up from children.
+ const isLoadingModels = useIsFetching({ queryKey: ["models"] }) > 0;
const queryClient = useQueryClient();
@@ -132,7 +132,6 @@ const OnboardingCard = ({
}
const handleSetModelProvider = (provider: string) => {
- setIsLoadingModels(false);
setModelProvider(provider);
setSettings({
[isEmbedding ? "embedding_provider" : "llm_provider"]: provider,
@@ -196,9 +195,19 @@ const OnboardingCard = ({
// Track which tasks we've already handled to prevent infinite loops
const handledFailedTasksRef = useRef<Set<string>>(new Set());
- // Ref for the completion timeout so it persists across effect re-runs
- const completeTimeoutRef = useRef<ReturnType<typeof setTimeout>>(undefined);
- useEffect(() => () => clearTimeout(completeTimeoutRef.current), []);
+ // Delay calling onComplete so the "Done" step is briefly visible.
+ const [pendingComplete, setPendingComplete] = useState(false);
+ const onCompleteEvent = useEffectEvent(onComplete);
+ useEffect(() => {
+ if (!pendingComplete) {
+ return;
+ }
+ const timeoutId = setTimeout(() => {
+ onCompleteEvent();
+ setPendingComplete(false);
+ }, 1000);
+ return () => clearTimeout(timeoutId);
+ }, [pendingComplete]);
// Query tasks to track completion
const { data: tasks } = useGetTasksQuery({
@@ -250,9 +259,7 @@ const OnboardingCard = ({
category: "Setup",
});
setCurrentStep(totalSteps);
- setTimeout(() => {
- onComplete();
- }, 1000);
+ setPendingComplete(true);
} else {
trackProcessSuccess({
processType: "Onboarding",
@@ -264,13 +271,14 @@ const OnboardingCard = ({
}
},
onError: (error) => {
+ const message = formatProviderErrorMessage(error.message);
trackProcessFailure({
processType: "Onboarding",
process: isEmbedding ? "Embedding Setup" : "LLM Setup",
- resultValue: error.message,
+ resultValue: message,
category: "Setup",
});
- setError(error.message);
+ setError(message);
setCurrentStep(totalSteps);
rollbackMutation.mutate({ embedding_only: isEmbedding });
},
@@ -340,31 +348,28 @@ const OnboardingCard = ({
// Mark this task as handled to prevent infinite loops
handledFailedTasksRef.current.add(taskWithFailure.task_id);
- // Extract error messages from failed files
+ // Prefer sanitized user_facing_message from enhanced tasks, then raw error.
const errorMessages: string[] = [];
if (taskWithFailure.files) {
Object.values(taskWithFailure.files).forEach((file) => {
- if (
- (file.status === "failed" || file.status === "error") &&
- file.error
- ) {
- errorMessages.push(file.error);
+ if (file.status !== "failed" && file.status !== "error") {
+ return;
+ }
+ const msg = file.user_facing_message || file.error;
+ if (msg) {
+ errorMessages.push(msg);
}
});
}
- // Also check task-level error
if (taskWithFailure.error) {
errorMessages.push(taskWithFailure.error);
}
- // Use the first error message, or a generic message if no errors found
- const errorMessage =
- errorMessages.length > 0
- ? errorMessages[0]
- : "Sample data ingestion failed. Please try again.";
+ const errorMessage = formatProviderErrorMessage(
+ errorMessages[0] || "Sample data ingestion failed. Please try again.",
+ );
- // Set error message and jump back one step (exactly like onboardingMutation.onError)
trackProcessFailure({
processType: "Onboarding",
process: "Sample Data Ingest",
@@ -376,7 +381,7 @@ const OnboardingCard = ({
failed_files: taskWithFailure.failed_files,
});
- clearTimeout(completeTimeoutRef.current);
+ setPendingComplete(false);
setError(errorMessage);
setCurrentStep(totalSteps);
rollbackMutation.mutate({ embedding_only: isEmbedding });
@@ -408,18 +413,13 @@ const OnboardingCard = ({
successful_files: completedTask?.successful_files,
});
- // Set to final step to show "Done"
+ // Set to final step to show "Done", then delay onComplete via pendingComplete.
setCurrentStep(totalSteps);
- // Wait a bit before completing — stored in a ref so the timeout
- // survives the re-render caused by setCurrentStep above.
- completeTimeoutRef.current = setTimeout(() => {
- onComplete();
- }, 1000);
+ setPendingComplete(true);
}
}, [
tasks,
currentStep,
- onComplete,
isCompleted,
isEmbedding,
totalSteps,
@@ -673,7 +673,6 @@ const OnboardingCard = ({
<TabsContent value="anthropic">
<AnthropicOnboarding
setSettings={setSettings}
- setIsLoadingModels={setIsLoadingModels}
isEmbedding={isEmbedding}
hasEnvApiKey={
currentSettings?.providers?.anthropic?.has_api_key ===
@@ -685,7 +684,6 @@ const OnboardingCard = ({
<TabsContent value="openai">
<OpenAIOnboarding
setSettings={setSettings}
- setIsLoadingModels={setIsLoadingModels}
isEmbedding={isEmbedding}
hasEnvApiKey={
currentSettings?.providers?.openai?.has_api_key === true
@@ -698,7 +696,6 @@ const OnboardingCard = ({
<TabsContent value="watsonx">
<IBMOnboarding
setSettings={setSettings}
- setIsLoadingModels={setIsLoadingModels}
isEmbedding={isEmbedding}
alreadyConfigured={
providerAlreadyConfigured && modelProvider === "watsonx"
@@ -718,7 +715,6 @@ const OnboardingCard = ({
<TabsContent value="ollama">
<OllamaOnboarding
setSettings={setSettings}
- setIsLoadingModels={setIsLoadingModels}
isEmbedding={isEmbedding}
alreadyConfigured={
providerAlreadyConfigured && modelProvider === "ollama"
diff --git a/frontend/app/onboarding/_components/openai-onboarding.tsx b/frontend/app/onboarding/_components/openai-onboarding.tsx
index abe71936f..338520c36 100644
--- a/frontend/app/onboarding/_components/openai-onboarding.tsx
+++ b/frontend/app/onboarding/_components/openai-onboarding.tsx
@@ -1,5 +1,5 @@
import type { Dispatch, SetStateAction } from "react";
-import { useEffect, useState } from "react";
+import { useState } from "react";
import OpenAILogo from "@/components/icons/openai-logo";
import { LabelInput } from "@/components/label-input";
import { LabelWrapper } from "@/components/label-wrapper";
@@ -18,13 +18,11 @@ import { AdvancedOnboarding } from "./advanced";
export function OpenAIOnboarding({
setSettings,
- setIsLoadingModels,
isEmbedding = false,
hasEnvApiKey = false,
alreadyConfigured = false,
}: {
setSettings: Dispatch<SetStateAction<OnboardingVariables>>;
- setIsLoadingModels?: (isLoading: boolean) => void;
isEmbedding?: boolean;
hasEnvApiKey?: boolean;
alreadyConfigured?: boolean;
@@ -35,25 +33,25 @@ export function OpenAIOnboarding({
);
const debouncedApiKey = useDebouncedValue(apiKey, 500);
- // Fetch models from API when API key is provided
const {
data: modelsData,
isLoading: isLoadingModels,
+ isFetching: isFetchingModels,
error: modelsError,
} = useGetOpenAIModelsQuery(
getFromEnv
- ? { apiKey: "" }
+ ? { useEnvKey: true }
: debouncedApiKey
- ? { apiKey: debouncedApiKey }
+ ? { apiKey: debouncedApiKey, useEnvKey: false }
: undefined,
{
- // Only validate when the user opts in (env) or provides a key.
- // If a key was previously configured, let the user decide to reuse or replace it
- // without triggering an immediate validation error.
enabled: debouncedApiKey !== "" || getFromEnv || alreadyConfigured,
},
);
- // Use custom hook for model selection logic
+
+ const showModelsError =
+ !!modelsError && !isLoadingModels && !isFetchingModels;
+
const {
languageModel,
embeddingModel,
@@ -72,15 +70,11 @@ export function OpenAIOnboarding({
setLanguageModel?.("");
};
- useEffect(() => {
- setIsLoadingModels?.(isLoadingModels);
- }, [isLoadingModels, setIsLoadingModels]);
-
- // Update settings when values change
useUpdateSettings(
"openai",
{
- apiKey,
+ apiKey: getFromEnv || alreadyConfigured ? undefined : apiKey,
+ clearApiKey: getFromEnv,
languageModel,
embeddingModel,
},
@@ -122,7 +116,7 @@ export function OpenAIOnboarding({
<LabelInput
label="OpenAI API key"
helperText="The API key for your OpenAI account."
- className={modelsError ? "!border-destructive" : ""}
+ className={showModelsError ? "!border-destructive" : ""}
id="api-key"
type="password"
required
@@ -133,7 +127,6 @@ export function OpenAIOnboarding({
}
value={apiKey}
onChange={(e) => setApiKey(e.target.value)}
- // Even if a key exists, allow replacing it to avoid getting stuck on stale creds.
disabled={false}
/>
{alreadyConfigured && (
@@ -142,15 +135,13 @@ export function OpenAIOnboarding({
one.
</p>
)}
- {isLoadingModels && (
+ {(isLoadingModels || isFetchingModels) && (
<p className="text-mmd text-muted-foreground">
Validating API key...
</p>
)}
- {modelsError && (
- <p className="text-mmd text-destructive">
- Invalid OpenAI API key. Verify or replace the key.
- </p>
+ {showModelsError && (
+ <p className="text-mmd text-destructive">{modelsError.message}</p>
)}
</div>
)}
diff --git a/frontend/app/onboarding/_hooks/useUpdateSettings.ts b/frontend/app/onboarding/_hooks/useUpdateSettings.ts
index dc9ae9e37..45dfe7b58 100644
--- a/frontend/app/onboarding/_hooks/useUpdateSettings.ts
+++ b/frontend/app/onboarding/_hooks/useUpdateSettings.ts
@@ -4,12 +4,29 @@ import type { OnboardingVariables } from "../../api/mutations/useOnboardingMutat
interface ConfigValues {
apiKey?: string;
+ /** When true, clear the provider key (e.g. environment-key mode). */
+ clearApiKey?: boolean;
endpoint?: string;
projectId?: string;
languageModel?: string;
embeddingModel?: string;
}
+function resolveApiKey(
+ apiKey: string | undefined,
+ clearApiKey: boolean | undefined,
+ previous: string | undefined,
+): string {
+ if (clearApiKey) {
+ return "";
+ }
+ // Explicit empty clears a typed key; omit (undefined) to reuse previous.
+ if (apiKey !== undefined) {
+ return apiKey;
+ }
+ return previous || "";
+}
+
export function useUpdateSettings(
provider: string,
config: ConfigValues,
@@ -31,15 +48,26 @@ export function useUpdateSettings(
updatedSettings.llm_provider = provider;
}
- // Map provider-specific API keys
- if (config.apiKey) {
- if (provider === "openai") {
- updatedSettings.openai_api_key = config.apiKey;
- } else if (provider === "anthropic") {
- updatedSettings.anthropic_api_key = config.apiKey;
- } else if (provider === "watsonx") {
- updatedSettings.watsonx_api_key = config.apiKey;
- }
+ // Map provider-specific API keys. undefined preserves prior credentials;
+ // "" or clearApiKey clears; a non-empty string replaces.
+ if (provider === "openai") {
+ updatedSettings.openai_api_key = resolveApiKey(
+ config.apiKey,
+ config.clearApiKey,
+ prev.openai_api_key,
+ );
+ } else if (provider === "anthropic") {
+ updatedSettings.anthropic_api_key = resolveApiKey(
+ config.apiKey,
+ config.clearApiKey,
+ prev.anthropic_api_key,
+ );
+ } else if (provider === "watsonx") {
+ updatedSettings.watsonx_api_key = resolveApiKey(
+ config.apiKey,
+ config.clearApiKey,
+ prev.watsonx_api_key,
+ );
}
// Map provider-specific endpoints
@@ -61,6 +89,7 @@ export function useUpdateSettings(
}, [
provider,
config.apiKey,
+ config.clearApiKey,
config.endpoint,
config.projectId,
config.languageModel,
diff --git a/frontend/app/settings/_components/anthropic-settings-form.tsx b/frontend/app/settings/_components/anthropic-settings-form.tsx
index 14d09e702..fcfc5ab81 100644
--- a/frontend/app/settings/_components/anthropic-settings-form.tsx
+++ b/frontend/app/settings/_components/anthropic-settings-form.tsx
@@ -18,9 +18,7 @@ export function AnthropicSettingsForm({
formState: { errors },
} = useFormContext<AnthropicSettingsFormData>();
- const apiKeyError = modelsError
- ? "Invalid Anthropic API key. Verify or replace the key."
- : errors.apiKey?.message;
+ const apiKeyError = modelsError?.message || errors.apiKey?.message;
return (
<div className="space-y-4">
diff --git a/frontend/app/settings/_components/ollama-settings-form.tsx b/frontend/app/settings/_components/ollama-settings-form.tsx
index 221d4fcc8..ad1655edf 100644
--- a/frontend/app/settings/_components/ollama-settings-form.tsx
+++ b/frontend/app/settings/_components/ollama-settings-form.tsx
@@ -18,9 +18,7 @@ export function OllamaSettingsForm({
formState: { errors },
} = useFormContext<OllamaSettingsFormData>();
- const endpointError = modelsError
- ? "Connection failed. Check your Ollama server URL."
- : errors.endpoint?.message;
+ const endpointError = modelsError?.message || errors.endpoint?.message;
return (
<div className="space-y-4">
diff --git a/frontend/app/settings/_components/openai-settings-form.tsx b/frontend/app/settings/_components/openai-settings-form.tsx
index b47ecac98..20bc625d2 100644
--- a/frontend/app/settings/_components/openai-settings-form.tsx
+++ b/frontend/app/settings/_components/openai-settings-form.tsx
@@ -18,9 +18,7 @@ export function OpenAISettingsForm({
formState: { errors },
} = useFormContext<OpenAISettingsFormData>();
- const apiKeyError = modelsError
- ? "Invalid OpenAI API key. Verify or replace the key."
- : errors.apiKey?.message;
+ const apiKeyError = modelsError?.message || errors.apiKey?.message;
return (
<div className="space-y-4">
diff --git a/frontend/app/settings/_components/watsonx-settings-form.tsx b/frontend/app/settings/_components/watsonx-settings-form.tsx
index a31004c07..458c95940 100644
--- a/frontend/app/settings/_components/watsonx-settings-form.tsx
+++ b/frontend/app/settings/_components/watsonx-settings-form.tsx
@@ -135,9 +135,7 @@ export function WatsonxSettingsForm({
</p>
)}
{modelsError && (
- <p className="text-sm text-destructive">
- Connection failed. Check your configuration.
- </p>
+ <p className="text-sm text-destructive">{modelsError.message}</p>
)}
</div>
<p className="text-sm text-muted-foreground">
diff --git a/frontend/components/provider-health-banner.tsx b/frontend/components/provider-health-banner.tsx
index faa345c10..749252521 100644
--- a/frontend/components/provider-health-banner.tsx
+++ b/frontend/components/provider-health-banner.tsx
@@ -23,7 +23,9 @@ export function useProviderHealth() {
error,
isError,
} = useProviderHealthQuery({
- test_completion: hasChatError, // Use test_completion=true when chat errors occur
+ // After a chat/ingest failure, probe completion so the banner shows the
+ // real error (disabled key, missing model, etc.) — not only IAM auth.
+ test_completion: hasChatError,
});
const isHealthy = health?.status === "healthy" && !isError;
diff --git a/frontend/contexts/task-context.tsx b/frontend/contexts/task-context.tsx
index 981f5f6f0..f6e8c74d7 100644
--- a/frontend/contexts/task-context.tsx
+++ b/frontend/contexts/task-context.tsx
@@ -321,6 +321,12 @@ export function TaskProvider({ children }: { children: React.ReactNode }) {
}
const fileError = (() => {
+ if (
+ typeof fileInfoEntry.user_facing_message === "string" &&
+ fileInfoEntry.user_facing_message.trim().length > 0
+ ) {
+ return fileInfoEntry.user_facing_message.trim();
+ }
if (
typeof fileInfoEntry.error === "string" &&
fileInfoEntry.error.trim().length > 0
diff --git a/frontend/lib/chat-stream-errors.test.ts b/frontend/lib/chat-stream-errors.test.ts
index 7a37dc758..a0c508a4b 100644
--- a/frontend/lib/chat-stream-errors.test.ts
+++ b/frontend/lib/chat-stream-errors.test.ts
@@ -58,7 +58,7 @@ describe("extractStreamProviderError", () => {
'Failed to authenticate with IBM Watson: {"errorCode":"BXNIM0415E","errorMessage":"Provided API key could not be found."}',
},
}),
- "Provided API key could not be found.",
+ "Provided API key is Invalid.",
);
});
});
@@ -146,7 +146,7 @@ describe("formatProviderErrorMessage", () => {
formatProviderErrorMessage(
'Failed to authenticate. Error: {"errorCode":"BXNIM0415E","errorMessage":"Provided API key could not be found."} trailing junk',
),
- "Provided API key could not be found.",
+ "Provided API key is Invalid.",
);
});
diff --git a/frontend/lib/chat-stream-errors.ts b/frontend/lib/chat-stream-errors.ts
index af2b5671c..6ea5edacf 100644
--- a/frontend/lib/chat-stream-errors.ts
+++ b/frontend/lib/chat-stream-errors.ts
@@ -165,6 +165,15 @@ export function looksLikeProviderErrorContent(text: string): boolean {
return false;
}
+/** Rewrite provider-specific messages into clearer user-facing copy. */
+function humanizeProviderErrorMessage(message: string): string {
+ // IBM IAM returns "could not be found" for invalid/unknown keys.
+ if (message.toLowerCase().includes("api key could not be found")) {
+ return "Provided API key is Invalid.";
+ }
+ return message;
+}
+
/**
* Strip embedded provider JSON payloads so chat never shows raw error objects.
*/
@@ -177,7 +186,7 @@ export function formatProviderErrorMessage(text: string): string {
const direct = tryParseJsonMessage(trimmed);
if (direct) {
// Pure JSON payloads: prefer the extracted message only.
- return stripErrorLabelPrefixes(direct);
+ return humanizeProviderErrorMessage(stripErrorLabelPrefixes(direct));
}
const jsonBlob = extractBalancedJsonObject(trimmed);
@@ -185,7 +194,7 @@ export function formatProviderErrorMessage(text: string): string {
const nested = tryParseJsonMessage(jsonBlob);
if (nested) {
// Embedded provider JSON already has the real message — drop wrappers.
- return stripErrorLabelPrefixes(nested);
+ return humanizeProviderErrorMessage(stripErrorLabelPrefixes(nested));
}
const prefix = stripErrorLabelPrefixes(
trimmed
@@ -194,7 +203,7 @@ export function formatProviderErrorMessage(text: string): string {
.trim(),
);
if (prefix) {
- return prefix;
+ return humanizeProviderErrorMessage(prefix);
}
}
@@ -208,11 +217,11 @@ export function formatProviderErrorMessage(text: string): string {
.trim(),
);
if (prefix) {
- return prefix;
+ return humanizeProviderErrorMessage(prefix);
}
}
- return trimmed;
+ return humanizeProviderErrorMessage(trimmed);
}
/**
diff --git a/frontend/lib/task-error-display.ts b/frontend/lib/task-error-display.ts
index b6b4c9a49..340c1c88b 100644
--- a/frontend/lib/task-error-display.ts
+++ b/frontend/lib/task-error-display.ts
@@ -3,6 +3,7 @@ import type {
TaskFailurePhase,
TaskFileEntry,
} from "@/app/api/queries/useGetTasksQuery";
+import { formatProviderErrorMessage } from "@/lib/chat-stream-errors";
export const FILE_ERROR_MAX_LINE_LENGTH = 80;
@@ -156,19 +157,19 @@ export function resolveTaskFileError(
typeof fileInfo.result.warning === "string" &&
fileInfo.result.warning.trim()
) {
- return fileInfo.result.warning.trim();
+ return formatProviderErrorMessage(fileInfo.result.warning.trim());
}
if (typeof fileInfo.user_facing_message === "string") {
const message = fileInfo.user_facing_message.trim();
if (message) {
- return message;
+ return formatProviderErrorMessage(message);
}
}
if (typeof fileInfo.error === "string" && fileInfo.error.trim()) {
- return fileInfo.error.trim();
+ return formatProviderErrorMessage(fileInfo.error.trim());
}
if (typeof taskError === "string" && taskError.trim()) {
- return taskError.trim();
+ return formatProviderErrorMessage(taskError.trim());
}
return "Unknown error";
}
diff --git a/frontend/tests/pages/Settings.ts b/frontend/tests/pages/Settings.ts
index d890b6a47..935cc91ea 100644
--- a/frontend/tests/pages/Settings.ts
+++ b/frontend/tests/pages/Settings.ts
@@ -43,9 +43,9 @@ export class Settings {
private readonly removeAnywayButton = () =>
this.page.getByRole("button", { name: "Remove Anyway" });
private readonly watsonxConnectionErrorMessage = () =>
- this.page.getByText("Connection failed. Check your configuration.");
+ this.page.locator('[role="dialog"] .text-destructive').first();
private readonly openaiConnectionErrorMessage = () =>
- this.page.getByText("Invalid OpenAI API key. Verify or replace the key.");
+ this.page.locator('[role="dialog"] .text-destructive').first();
/**
* Get locator for configure button by provider name
@@ -356,7 +356,7 @@ export class Settings {
await expect(successToast.or(errorMsg)).toBeVisible({ timeout: 30000 });
if (await errorMsg.isVisible()) {
throw new Error(
- "Watsonx.ai configuration failed: Connection failed. Check your configuration (invalid API Key, Project ID, or Endpoint).",
+ `Watsonx.ai configuration failed: ${await errorMsg.textContent()}`,
);
}
logger.info("Watsonx.ai configuration completed");
@@ -444,7 +444,7 @@ export class Settings {
await expect(successToast.or(errorMsg)).toBeVisible({ timeout: 30000 });
if (await errorMsg.isVisible()) {
throw new Error(
- "OpenAI configuration failed: Invalid OpenAI API key. Verify or replace the key.",
+ `OpenAI configuration failed: ${await errorMsg.textContent()}`,
);
}
logger.info("OpenAI configuration completed");
diff --git a/src/agent.py b/src/agent.py
index bfeec9114..031cbc19a 100644
--- a/src/agent.py
+++ b/src/agent.py
@@ -671,7 +671,9 @@ async def async_chat_stream(
)
except Exception as e:
logger.error(f"Error in chat stream: {e}", exc_info=True)
- error_text = _format_provider_error_message(e)
+ from api.provider_validation import resolve_chat_stream_error_message_async
+
+ error_text = await resolve_chat_stream_error_message_async(e)
display_text = _provider_error_display_text(error_text, full_response)
conversation_state["messages"].append(
{
@@ -988,14 +990,14 @@ async def async_langflow_chat_stream(
from api.provider_validation import (
looks_like_provider_error_content,
- resolve_chat_stream_error_message,
+ resolve_chat_stream_error_message_async,
)
# Credential failures are often streamed as plain assistant text with no
# exception. Sanitize, mark as error, and emit a terminal error chunk so
# the client shows the error card instead of raw JSON.
if error_occurred or looks_like_provider_error_content(full_response):
- display_text = resolve_chat_stream_error_message(full_response)
+ display_text = await resolve_chat_stream_error_message_async(full_response)
conversation_state["messages"].append(
{
"role": "assistant",
@@ -1048,12 +1050,12 @@ async def async_langflow_chat_stream(
logger.warning(f"Failed to claim session ownership: {e}")
except Exception as e:
logger.error(f"Error in langflow chat stream: {e}", exc_info=True)
- from api.provider_validation import resolve_chat_stream_error_message
+ from api.provider_validation import resolve_chat_stream_error_message_async
- error_text = resolve_chat_stream_error_message(e)
+ error_text = await resolve_chat_stream_error_message_async(e)
display_text = _provider_error_display_text(error_text, full_response)
if full_response:
- display_text = resolve_chat_stream_error_message(display_text)
+ display_text = await resolve_chat_stream_error_message_async(display_text)
conversation_state["messages"].append(
{
diff --git a/src/api/models.py b/src/api/models.py
index 9311f681d..5c884ad1e 100644
--- a/src/api/models.py
+++ b/src/api/models.py
@@ -1,7 +1,14 @@
+import re
+
+import httpx
from fastapi import Depends
from fastapi.responses import JSONResponse
from pydantic import BaseModel
+from api.provider_validation import (
+ is_provider_credential_error,
+ sanitize_provider_error_content,
+)
from config.settings import get_openrag_config
from dependencies import get_models_service, require_permission
from session_manager import User
@@ -9,6 +16,21 @@ from utils.logging_config import get_logger
logger = get_logger(__name__)
+_CREDENTIAL_PATTERNS = (
+ # OpenAI / Anthropic / Langflow-style secret prefixes echoed by providers.
+ re.compile(r"\bsk-(?:ant-|lf-)?[A-Za-z0-9_\-]{3,}\b"),
+ re.compile(r"(?i)\bBearer\s+[A-Za-z0-9._\-]+\b"),
+ re.compile(r"(?i)\b(?:api[_-]?key|apikey|x-api-key)\s*[:=]\s*['\"]?[^\s'\",}]+"),
+)
+
+
+def _redact_credentials(message: str) -> str:
+ """Strip provider-echoed secrets before returning errors to clients."""
+ redacted = message
+ for pattern in _CREDENTIAL_PATTERNS:
+ redacted = pattern.sub("[REDACTED]", redacted)
+ return redacted
+
class OpenAIBody(BaseModel):
api_key: str | None = None
@@ -24,6 +46,35 @@ class IBMBody(BaseModel):
project_id: str | None = None
+def _models_error_response(exc: Exception) -> JSONResponse:
+ """Map model-route failures to client (400) vs upstream (502) vs server (500).
+
+ ``models_service`` raises bare ``Exception(user_message)`` for actionable
+ provider/config failures (invalid key, empty model list, bad project). Those
+ must reach onboarding as sanitized text. Unexpected internals (e.g.
+ ``RuntimeError``) stay behind the generic 500.
+ """
+ if isinstance(exc, (httpx.TimeoutException, httpx.RequestError)):
+ return JSONResponse(
+ {"error": "Unable to reach the model provider. Please try again."},
+ status_code=502,
+ )
+
+ error = sanitize_provider_error_content(exc)
+ redacted = _redact_credentials(error)
+ if is_provider_credential_error(exc) or is_provider_credential_error(error):
+ return JSONResponse({"error": redacted}, status_code=400)
+ if isinstance(exc, (ValueError, TypeError)) or type(exc) is Exception:
+ # Bare Exception is the models_service user-facing contract; keep JSON
+ # / traceback leaks behind the generic response.
+ if redacted and "{" not in redacted and "}" not in redacted:
+ return JSONResponse({"error": redacted}, status_code=400)
+ return JSONResponse(
+ {"error": "An unexpected error occurred while fetching models."},
+ status_code=500,
+ )
+
+
async def get_openai_models(
body: OpenAIBody | None = None,
models_service=Depends(get_models_service),
@@ -49,7 +100,7 @@ async def get_openai_models(
return JSONResponse(models)
except Exception as e:
logger.error(f"Failed to get OpenAI models: {str(e)}")
- return JSONResponse({"error": "Failed to retrieve OpenAI models"}, status_code=500)
+ return _models_error_response(e)
async def get_anthropic_models(
@@ -79,7 +130,7 @@ async def get_anthropic_models(
return JSONResponse(models)
except Exception as e:
logger.error(f"Failed to get Anthropic models: {str(e)}")
- return JSONResponse({"error": "Failed to retrieve Anthropic models"}, status_code=500)
+ return _models_error_response(e)
async def get_ollama_models(
@@ -106,7 +157,7 @@ async def get_ollama_models(
return JSONResponse(models)
except Exception as e:
logger.error(f"Failed to get Ollama models: {str(e)}")
- return JSONResponse({"error": "Failed to retrieve Ollama models"}, status_code=500)
+ return _models_error_response(e)
async def get_ibm_models(
@@ -163,4 +214,4 @@ async def get_ibm_models(
return JSONResponse(models)
except Exception as e:
logger.error(f"Failed to get IBM models: {str(e)}")
- return JSONResponse({"error": "Failed to retrieve IBM models"}, status_code=500)
+ return _models_error_response(e)
diff --git a/src/api/provider_health.py b/src/api/provider_health.py
index bc5aab9a7..dddaeb6bd 100644
--- a/src/api/provider_health.py
+++ b/src/api/provider_health.py
@@ -6,7 +6,7 @@ import httpx
from fastapi import Depends
from fastapi.responses import JSONResponse
-from api.provider_validation import format_provider_error_message, validate_provider_setup
+from api.provider_validation import sanitize_provider_error_content, validate_provider_setup
from config.settings import get_openrag_config
from dependencies import require_permission
from session_manager import User
@@ -195,10 +195,10 @@ async def check_provider_health(
llm_error = None # Don't treat as error
logger.info(f"LLM provider ({provider}) appears busy: {str(e)}")
else:
- llm_error = format_provider_error_message(e)
+ llm_error = sanitize_provider_error_content(e)
logger.error(f"LLM provider ({provider}) validation timed out: {llm_error}")
except Exception as e:
- llm_error = format_provider_error_message(e)
+ llm_error = sanitize_provider_error_content(e)
logger.error(f"LLM provider ({provider}) validation failed: {llm_error}")
# Validate embedding provider
@@ -229,12 +229,12 @@ async def check_provider_health(
embedding_error = None # Don't treat as error
logger.info(f"Embedding provider ({embedding_provider}) appears busy: {str(e)}")
else:
- embedding_error = format_provider_error_message(e)
+ embedding_error = sanitize_provider_error_content(e)
logger.error(
f"Embedding provider ({embedding_provider}) validation timed out: {embedding_error}"
)
except Exception as e:
- embedding_error = format_provider_error_message(e)
+ embedding_error = sanitize_provider_error_content(e)
logger.error(
f"Embedding provider ({embedding_provider}) validation failed: {embedding_error}"
)
@@ -283,7 +283,7 @@ async def check_provider_health(
except Exception as e:
if _health_leader_key:
provider_health_cache.release_error(_health_leader_key)
- error_message = format_provider_error_message(e)
+ error_message = sanitize_provider_error_content(e)
logger.error(f"Provider health check failed for {provider}: {error_message}")
return JSONResponse(
diff --git a/src/api/provider_validation.py b/src/api/provider_validation.py
index 494a80098..d23753cb3 100644
--- a/src/api/provider_validation.py
+++ b/src/api/provider_validation.py
@@ -87,6 +87,15 @@ def _extract_balanced_json_object(text: str) -> str | None:
return None
+def _humanize_provider_error_message(message: str) -> str:
+ """Rewrite provider-specific messages into clearer user-facing copy."""
+ lowered = message.lower()
+ # IBM IAM returns "could not be found" for invalid/unknown keys.
+ if "api key could not be found" in lowered:
+ return "Provided API key is Invalid."
+ return message
+
+
def format_provider_error_message(exc: BaseException | str) -> str:
"""Return a concise, user-facing provider error string from an exception or text."""
text = _strip_error_label_prefixes((str(exc) if not isinstance(exc, str) else exc).strip())
@@ -96,16 +105,16 @@ def format_provider_error_message(exc: BaseException | str) -> str:
parsed = _parse_json_error_message(text)
if parsed != text:
# Pure JSON (or JSON-shaped) payloads: prefer the extracted message only.
- return _strip_error_label_prefixes(parsed)
+ return _humanize_provider_error_message(_strip_error_label_prefixes(parsed))
json_blob = _extract_balanced_json_object(text)
if json_blob:
nested = _parse_json_error_message(json_blob)
if nested != json_blob:
# Embedded provider JSON already has the real message — drop wrappers.
- return _strip_error_label_prefixes(nested)
+ return _humanize_provider_error_message(_strip_error_label_prefixes(nested))
- return text
+ return _humanize_provider_error_message(text)
def is_provider_credential_error(text: str | BaseException | None) -> bool:
@@ -288,24 +297,126 @@ async def probe_provider_credential_error() -> str | None:
return None
+async def probe_chat_llm_error() -> str | None:
+ """Return a cleaned error if the configured chat LLM fails auth or inference.
+
+ Unlike :func:`probe_provider_credential_error`, this runs a completion check
+ against the selected ``llm_model`` so missing/deprecated models surface
+ instead of being misreported as API-key failures (or left as opaque
+ Langflow text).
+ """
+ from config.settings import get_openrag_config
+
+ config = get_openrag_config()
+ provider = config.agent.llm_provider
+ llm_model = (config.agent.llm_model or "").strip()
+ if not provider or not llm_model:
+ return None
+
+ provider_config = config.get_llm_provider_config()
+ if provider_config is None:
+ return None
+
+ api_key = getattr(provider_config, "api_key", None)
+ endpoint = getattr(provider_config, "endpoint", None)
+ if provider == "ollama":
+ if not endpoint:
+ return None
+ elif not api_key:
+ return None
+
+ try:
+ # Pass only llm_model so validate_provider_setup runs completion (not
+ # the embedding branch of the test_completion if/elif).
+ await validate_provider_setup(
+ provider=provider,
+ api_key=api_key,
+ llm_model=llm_model,
+ endpoint=endpoint,
+ project_id=getattr(provider_config, "project_id", None),
+ test_completion=True,
+ )
+ except Exception as probe_exc:
+ return sanitize_provider_error_content(probe_exc)
+ return None
+
+
+async def probe_embedding_error() -> str | None:
+ """Return a cleaned error if the configured embedding model fails auth or inference."""
+ from config.settings import get_openrag_config
+
+ config = get_openrag_config()
+ provider = config.knowledge.embedding_provider
+ embedding_model = (config.knowledge.embedding_model or "").strip()
+ if not provider or not embedding_model:
+ return None
+
+ provider_config = config.get_embedding_provider_config()
+ if provider_config is None:
+ return None
+
+ api_key = getattr(provider_config, "api_key", None)
+ endpoint = getattr(provider_config, "endpoint", None)
+ if provider == "ollama":
+ if not endpoint:
+ return None
+ elif not api_key:
+ return None
+
+ try:
+ await validate_provider_setup(
+ provider=provider,
+ api_key=api_key,
+ embedding_model=embedding_model,
+ endpoint=endpoint,
+ project_id=getattr(provider_config, "project_id", None),
+ test_completion=True,
+ )
+ except Exception as probe_exc:
+ return sanitize_provider_error_content(probe_exc)
+ return None
+
+
async def resolve_ingest_error_message(exc: BaseException | str) -> str:
- """Prefer a credential message when Langflow fails auth or only reports a disconnect."""
- raw = (str(exc) if not isinstance(exc, str) else exc).strip() or "Ingestion failed"
+ """Sanitize ingest failures; probe model/setup when Langflow is opaque or mislabels auth.
+ Langflow often reports disconnects or "API key is invalid" when the real issue is a
+ missing/deprecated model. Mirror chat/banner diagnosis: test the configured embedding
+ and chat LLM (``test_completion``) before falling back to lightweight credential probes.
+ """
+ raw = (str(exc) if not isinstance(exc, str) else exc).strip() or "Ingestion failed"
cleaned = sanitize_provider_error_content(raw)
- if is_provider_credential_error(raw) or is_provider_credential_error(cleaned):
- return cleaned
- if is_langflow_transport_error(raw):
- probe = await probe_provider_credential_error()
- if probe:
+ should_probe = (
+ is_generic_upstream_error(cleaned)
+ or is_langflow_transport_error(raw)
+ or is_langflow_transport_error(cleaned)
+ or is_provider_credential_error(raw)
+ or is_provider_credential_error(cleaned)
+ )
+
+ if should_probe:
+ # Ingest primarily uses embeddings; also probe chat LLM so task UI matches the
+ # banner when the selected LLM model is missing/deprecated.
+ for probe_name, probe_fn in (
+ ("embedding", probe_embedding_error),
+ ("llm", probe_chat_llm_error),
+ ("credentials", probe_provider_credential_error),
+ ):
+ probe = await probe_fn()
+ if not probe:
+ continue
logger.info(
- "Ingest transport failure attributed to provider credentials",
- transport_error=raw,
- credential_error=probe,
+ "Ingest failure attributed via provider probe",
+ upstream_error=cleaned,
+ probe=probe_name,
+ resolved_error=probe,
)
return probe
+ if is_provider_credential_error(raw) or is_provider_credential_error(cleaned):
+ return cleaned
+
# Prefer the sanitized form whenever JSON / boilerplate was stripped.
if cleaned != raw and "{" not in cleaned:
return cleaned
@@ -313,18 +424,48 @@ async def resolve_ingest_error_message(exc: BaseException | str) -> str:
def resolve_chat_stream_error_message(text: str | BaseException | None) -> str:
- """Sanitize chat stream errors without probing providers.
-
- Do not infer API-key failures from opaque upstream text — that can hide the
- real failure. Callers should break Langflow session chaining after errors so
- the next turn is a fresh session that returns the detailed upstream message.
- """
+ """Sanitize chat stream errors synchronously (no provider probing)."""
raw = (str(text) if not isinstance(text, str) else text) if text is not None else ""
if not raw.strip():
return "An error occurred while generating a response."
return sanitize_provider_error_content(raw)
+async def resolve_chat_stream_error_message_async(
+ text: str | BaseException | None,
+) -> str:
+ """Sanitize chat stream errors, probing the active LLM for opaque upstream text.
+
+ Langflow often collapses auth/model failures to "An unknown error occurred."
+ Probe only when the sanitized message is still generic/transport-level so we
+ do not overwrite a more specific upstream failure.
+
+ Order matters: diagnose the selected chat LLM (credentials + model) before
+ scanning other configured keys. Otherwise a revoked secondary key can mask
+ the real chat failure (e.g. missing watsonx model).
+ """
+ cleaned = resolve_chat_stream_error_message(text)
+ if is_generic_upstream_error(cleaned) or is_langflow_transport_error(cleaned):
+ llm_probe = await probe_chat_llm_error()
+ if llm_probe:
+ logger.info(
+ "Chat stream opaque error attributed to configured LLM",
+ upstream_error=cleaned,
+ llm_error=llm_probe,
+ )
+ return llm_probe
+
+ cred_probe = await probe_provider_credential_error()
+ if cred_probe:
+ logger.info(
+ "Chat stream opaque error attributed to provider credentials",
+ upstream_error=cleaned,
+ credential_error=cred_probe,
+ )
+ return cred_probe
+ return cleaned
+
+
def _parse_json_error_message(error_text: str) -> str:
"""Parse JSON error message and extract just the message field."""
try:
@@ -395,15 +536,8 @@ def _extract_error_details(response: httpx.Response) -> str:
error_obj = error_data["error"]
if isinstance(error_obj, dict):
message = error_obj.get("message", "")
- error_type = error_obj.get("type", "")
- code = error_obj.get("code", "")
if message:
- details = message
- if error_type:
- details += f" (type: {error_type})"
- if code:
- details += f" (code: {code})"
- return details
+ return message
# Anthropic / generic: {"message": "..."}
if "message" in error_data:
@@ -588,7 +722,7 @@ async def _test_openai_lightweight_health(api_key: str) -> None:
logger.error(
f"OpenAI lightweight health check failed: {response.status_code} - {error_details}"
)
- raise Exception(f"OpenAI API key validation failed: {error_details}")
+ raise Exception(error_details)
logger.info("OpenAI lightweight health check passed")
@@ -658,7 +792,7 @@ async def _test_openai_completion_with_tools(api_key: str, llm_model: str) -> No
logger.error(
f"OpenAI completion test failed: {response.status_code} - {error_details}"
)
- raise Exception(f"OpenAI API error: {error_details}")
+ raise Exception(error_details)
logger.info("OpenAI completion with tool calling test passed")
@@ -696,7 +830,7 @@ async def _test_openai_embedding(api_key: str, embedding_model: str) -> None:
logger.error(
f"OpenAI embedding test failed: {response.status_code} - {error_details}"
)
- raise Exception(f"OpenAI API error: {error_details}")
+ raise Exception(error_details)
data = response.json()
if not data.get("data") or len(data["data"]) == 0:
@@ -737,7 +871,7 @@ async def _test_watsonx_lightweight_health(api_key: str, endpoint: str, project_
logger.error(
f"IBM IAM token request failed: {token_response.status_code} - {error_details}"
)
- raise Exception(f"Failed to authenticate with IBM Watson: {error_details}")
+ raise Exception(error_details)
bearer_token = token_response.json().get("access_token")
if not bearer_token:
@@ -775,7 +909,7 @@ async def _test_watsonx_completion_with_tools(
logger.error(
f"IBM IAM token request failed: {token_response.status_code} - {error_details}"
)
- raise Exception(f"Failed to authenticate with IBM Watson: {error_details}")
+ raise Exception(error_details)
bearer_token = token_response.json().get("access_token")
if not bearer_token:
@@ -828,7 +962,7 @@ async def _test_watsonx_completion_with_tools(
)
# If error_details is still JSON, parse it to extract just the message
parsed_details = _parse_json_error_message(error_details)
- raise Exception(f"IBM Watson API error: {parsed_details}")
+ raise Exception(parsed_details)
logger.info("IBM Watson completion with tool calling test passed")
@@ -843,7 +977,7 @@ async def _test_watsonx_completion_with_tools(
json_part = error_str.split("IBM Watson API error: ", 1)[1]
parsed_message = _parse_json_error_message(json_part)
if parsed_message != json_part:
- raise Exception(f"IBM Watson API error: {parsed_message}") from e
+ raise Exception(parsed_message) from e
raise
@@ -869,7 +1003,7 @@ async def _test_watsonx_embedding(
logger.error(
f"IBM IAM token request failed: {token_response.status_code} - {error_details}"
)
- raise Exception(f"Failed to authenticate with IBM Watson: {error_details}")
+ raise Exception(error_details)
bearer_token = token_response.json().get("access_token")
if not bearer_token:
@@ -905,7 +1039,7 @@ async def _test_watsonx_embedding(
)
# If error_details is still JSON, parse it to extract just the message
parsed_details = _parse_json_error_message(error_details)
- raise Exception(f"IBM Watson API error: {parsed_details}")
+ raise Exception(parsed_details)
data = response.json()
if not data.get("results") or len(data["results"]) == 0:
@@ -924,7 +1058,7 @@ async def _test_watsonx_embedding(
json_part = error_str.split("IBM Watson API error: ", 1)[1]
parsed_message = _parse_json_error_message(json_part)
if parsed_message != json_part:
- raise Exception(f"IBM Watson API error: {parsed_message}") from e
+ raise Exception(parsed_message) from e
raise
@@ -948,7 +1082,7 @@ async def _test_ollama_lightweight_health(endpoint: str) -> None:
logger.error(
f"Ollama lightweight health check failed: {response.status_code} - {error_details}"
)
- raise Exception(f"Ollama endpoint not responding: {error_details}")
+ raise Exception(error_details)
logger.info("Ollama lightweight health check passed")
@@ -1000,7 +1134,7 @@ async def _test_ollama_completion_with_tools(llm_model: str, endpoint: str) -> N
logger.error(
f"Ollama completion test failed: {response.status_code} - {error_details}"
)
- raise Exception(f"Ollama API error: {error_details}")
+ raise Exception(error_details)
logger.info("Ollama completion with tool calling test passed")
@@ -1035,7 +1169,7 @@ async def _test_ollama_embedding(embedding_model: str, endpoint: str) -> None:
logger.error(
f"Ollama embedding test failed: {response.status_code} - {error_details}"
)
- raise Exception(f"Ollama API error: {error_details}")
+ raise Exception(error_details)
data = response.json()
if not data.get("embedding"):
@@ -1077,7 +1211,7 @@ async def _test_anthropic_lightweight_health(api_key: str) -> None:
logger.error(
f"Anthropic lightweight health check failed: {response.status_code} - {error_details}"
)
- raise Exception(f"Anthropic API key validation failed: {error_details}")
+ raise Exception(error_details)
logger.info("Anthropic lightweight health check passed")
@@ -1131,7 +1265,7 @@ async def _test_anthropic_completion_with_tools(api_key: str, llm_model: str) ->
logger.error(
f"Anthropic completion test failed: {response.status_code} - {error_details}"
)
- raise Exception(f"Anthropic API error: {error_details}")
+ raise Exception(error_details)
logger.info("Anthropic completion with tool calling test passed")
diff --git a/src/api/settings/endpoints.py b/src/api/settings/endpoints.py
index 748444ee5..3ea215467 100644
--- a/src/api/settings/endpoints.py
+++ b/src/api/settings/endpoints.py
@@ -13,7 +13,7 @@ import json
from fastapi import Depends, HTTPException, Request
from fastapi.responses import JSONResponse
-from api.provider_validation import validate_provider_setup
+from api.provider_validation import sanitize_provider_error_content, validate_provider_setup
from api.settings.helpers import (
_affected_embedding_models,
_create_openrag_docs_filter,
@@ -454,7 +454,7 @@ async def update_settings(
except Exception as e:
logger.error(f"Provider validation failed: {str(e)}")
- return JSONResponse({"error": f"{str(e)}"}, status_code=400)
+ return JSONResponse({"error": sanitize_provider_error_content(e)}, status_code=400)
# Update configuration
# Only reached if validation passed or wasn't needed.
@@ -1144,7 +1144,7 @@ async def onboarding(
except Exception as e:
logger.error(f"Provider validation failed: {str(e)}")
return JSONResponse(
- {"error": str(e)},
+ {"error": sanitize_provider_error_content(e)},
status_code=400,
)
diff --git a/src/services/models_service.py b/src/services/models_service.py
index 0c498018b..e70ff9e87 100644
--- a/src/services/models_service.py
+++ b/src/services/models_service.py
@@ -2,6 +2,7 @@ import asyncio
import httpx
+from api.provider_validation import _extract_error_details, format_provider_error_message
from config.embedding_constants import OPENAI_DEFAULT_EMBEDDING_MODEL, OPENAI_EMBEDDING_MODEL_PREFIX
from config.model_constants import (
ANTHROPIC_DEFAULT_LANGUAGE_MODEL,
@@ -284,9 +285,7 @@ class ModelsService:
return result
else:
logger.error(f"Failed to fetch OpenAI models: {response.status_code}")
- raise Exception(
- f"OpenAI API returned status code {response.status_code}, {response.text}"
- )
+ raise Exception(format_provider_error_message(_extract_error_details(response)))
except Exception as e:
logger.error(f"Error fetching OpenAI models: {str(e)}")
@@ -348,9 +347,7 @@ class ModelsService:
return result
else:
logger.error(f"Failed to validate Anthropic API key: {response.status_code}")
- raise Exception(
- f"Anthropic API returned status code {response.status_code}, {response.text}"
- )
+ raise Exception(format_provider_error_message(_extract_error_details(response)))
except Exception as e:
logger.error(f"Error fetching Anthropic models: {str(e)}")
@@ -503,7 +500,7 @@ class ModelsService:
if token_response.status_code != 200:
raise Exception(
- f"Failed to get IBM IAM token: {token_response.status_code} - {token_response.text}"
+ format_provider_error_message(_extract_error_details(token_response))
)
token_data = token_response.json()
diff --git a/src/services/task_service.py b/src/services/task_service.py
index 7739d868e..13d1f64ea 100644
--- a/src/services/task_service.py
+++ b/src/services/task_service.py
@@ -1140,6 +1140,45 @@ class TaskService:
),
"actionable_by": "RETRYABLE",
}
+
+ # Prefer a sanitized specific provider/Langflow message (model missing,
+ # project misconfig, etc.) over a generic "unexpectedly" toast.
+ from api.provider_validation import (
+ is_generic_upstream_error,
+ is_provider_credential_error,
+ sanitize_provider_error_content,
+ )
+
+ cleaned = sanitize_provider_error_content(error)
+ if (
+ cleaned
+ and not is_generic_upstream_error(cleaned)
+ and "{" not in cleaned
+ and "}" not in cleaned
+ ):
+ lowered = cleaned.lower()
+ user_actionable = is_provider_credential_error(cleaned) or any(
+ marker in lowered
+ for marker in (
+ "model",
+ "project",
+ "not found",
+ "not properly configured",
+ "no models",
+ "unauthorized",
+ "forbidden",
+ "permission",
+ "quota",
+ "rate limit",
+ )
+ )
+ return {
+ "component": "langflow",
+ "failure_phase": "unknown",
+ "user_facing_message": cleaned,
+ "actionable_by": ("USER_ACTIONABLE" if user_actionable else "RETRYABLE"),
+ }
+
return {
"component": "langflow",
"failure_phase": "unknown",
diff --git a/tests/unit/test_langflow_stream_provider_errors.py b/tests/unit/test_langflow_stream_provider_errors.py
index 15fa3c504..8a862cf61 100644
--- a/tests/unit/test_langflow_stream_provider_errors.py
+++ b/tests/unit/test_langflow_stream_provider_errors.py
@@ -32,7 +32,7 @@ def test_format_provider_error_message_extracts_ibm_iam_error_message():
'"context":{"requestId":"abc","url":"https://iam.cloud.ibm.com"}}'
)
assert agent_module._format_provider_error_message(Exception(raw)) == (
- "Provided API key could not be found."
+ "Provided API key is Invalid."
)
@@ -53,8 +53,8 @@ def test_provider_error_display_text_drops_error_like_partial():
'{"errorMessage":"Provided API key could not be found."}'
)
assert (
- agent_module._provider_error_display_text("Provided API key could not be found.", partial)
- == "Provided API key could not be found."
+ agent_module._provider_error_display_text("Provided API key is Invalid.", partial)
+ == "Provided API key is Invalid."
)
@@ -376,7 +376,7 @@ async def test_langflow_stream_treats_credential_dump_content_as_error(
assert any(c.get("status") == "failed" for c in chunks)
error_chunk = next(c for c in chunks if c.get("status") == "failed")
assert "{" not in error_chunk["error"]["message"]
- assert "Provided API key could not be found" in error_chunk["error"]["message"]
+ assert "Provided API key is Invalid" in error_chunk["error"]["message"]
assert store_in_memory["stored"] == [(user_id, "resp_dump")]
assert store_in_memory["claimed"] == [(user_id, "resp_dump")]
stored = agent_module.active_conversations[user_id]["resp_dump"]
diff --git a/tests/unit/test_models_api_errors.py b/tests/unit/test_models_api_errors.py
new file mode 100644
index 000000000..f4d8a5c36
--- /dev/null
+++ b/tests/unit/test_models_api_errors.py
@@ -0,0 +1,136 @@
+"""Models API should return sanitized provider error messages."""
+
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from fastapi.responses import JSONResponse
+
+from api import models as models_api
+
+
+async def test_get_ibm_models_returns_sanitized_provider_error():
+ raw = (
+ '{"errorCode":"BXNIM0415E",'
+ '"errorMessage":"Provided API key could not be found.",'
+ '"context":{"requestId":"abc"}}'
+ )
+ models_service = SimpleNamespace(
+ get_ibm_models=AsyncMock(side_effect=Exception(raw)),
+ )
+
+ response = await models_api.get_ibm_models(
+ body=models_api.IBMBody(
+ api_key="bad-key",
+ endpoint="https://ca-tor.ml.cloud.ibm.com",
+ project_id="proj",
+ ),
+ models_service=models_service,
+ user=SimpleNamespace(),
+ )
+
+ assert isinstance(response, JSONResponse)
+ assert response.status_code == 400
+ payload = json.loads(response.body)
+ assert payload["error"] == "Provided API key is Invalid."
+
+
+async def test_get_openai_models_returns_sanitized_provider_error():
+ raw = json.dumps(
+ {
+ "error": {
+ "message": "Incorrect API key provided: sk-bad.",
+ "type": "invalid_request_error",
+ "code": "invalid_api_key",
+ }
+ }
+ )
+ models_service = SimpleNamespace(
+ get_openai_models=AsyncMock(side_effect=Exception(raw)),
+ )
+
+ response = await models_api.get_openai_models(
+ body=models_api.OpenAIBody(api_key="sk-bad"),
+ models_service=models_service,
+ user=SimpleNamespace(),
+ )
+
+ assert isinstance(response, JSONResponse)
+ assert response.status_code == 400
+ payload = json.loads(response.body)
+ assert payload["error"] == "Incorrect API key provided: [REDACTED]."
+ assert "sk-bad" not in payload["error"]
+
+
+async def test_get_openai_models_returns_502_on_transport_error():
+ import httpx
+
+ models_service = SimpleNamespace(
+ get_openai_models=AsyncMock(
+ side_effect=httpx.ConnectError("All connection attempts failed")
+ ),
+ )
+
+ response = await models_api.get_openai_models(
+ body=models_api.OpenAIBody(api_key="sk-test"),
+ models_service=models_service,
+ user=SimpleNamespace(),
+ )
+
+ assert isinstance(response, JSONResponse)
+ assert response.status_code == 502
+ payload = json.loads(response.body)
+ assert payload["error"] == "Unable to reach the model provider. Please try again."
+ assert "connection attempts" not in payload["error"].lower()
+
+
+async def test_get_openai_models_returns_500_on_unexpected_error():
+ models_service = SimpleNamespace(
+ get_openai_models=AsyncMock(side_effect=RuntimeError("boom secret-key")),
+ )
+
+ response = await models_api.get_openai_models(
+ body=models_api.OpenAIBody(api_key="sk-test"),
+ models_service=models_service,
+ user=SimpleNamespace(),
+ )
+
+ assert isinstance(response, JSONResponse)
+ assert response.status_code == 500
+ payload = json.loads(response.body)
+ assert payload["error"] == "An unexpected error occurred while fetching models."
+ assert "boom" not in payload["error"]
+
+
+async def test_get_ibm_models_returns_project_configuration_error():
+ """Bare Exception from models_service is the user-facing contract — do not 500."""
+ msg = (
+ "API key is valid, but no models are available. "
+ "This usually means your Watson Machine Learning (WML) project is not properly configured."
+ )
+ models_service = SimpleNamespace(
+ get_ibm_models=AsyncMock(side_effect=Exception(msg)),
+ )
+
+ response = await models_api.get_ibm_models(
+ body=models_api.IBMBody(
+ api_key="ok-key",
+ endpoint="https://ca-tor.ml.cloud.ibm.com",
+ project_id="proj",
+ ),
+ models_service=models_service,
+ user=SimpleNamespace(),
+ )
+
+ assert isinstance(response, JSONResponse)
+ assert response.status_code == 400
+ payload = json.loads(response.body)
+ assert payload["error"] == msg
diff --git a/tests/unit/test_provider_error_formatting.py b/tests/unit/test_provider_error_formatting.py
index 4a62f3716..6a36d43c8 100644
--- a/tests/unit/test_provider_error_formatting.py
+++ b/tests/unit/test_provider_error_formatting.py
@@ -22,7 +22,7 @@ def test_parse_ibm_iam_error_message():
'"errorMessage":"Provided API key could not be found.",'
'"context":{"requestId":"abc","url":"https://iam.cloud.ibm.com"}}'
)
- assert format_provider_error_message(raw) == "Provided API key could not be found."
+ assert format_provider_error_message(raw) == "Provided API key is Invalid."
def test_format_extracts_json_with_trailing_text():
@@ -34,7 +34,7 @@ def test_format_extracts_json_with_trailing_text():
"IBM WatsonX requires additional configuration parameters. "
"An error occurred while generating a response."
)
- assert format_provider_error_message(raw) == "Provided API key could not be found."
+ assert format_provider_error_message(raw) == "Provided API key is Invalid."
assert "{" not in sanitize_provider_error_content(raw)
@@ -82,7 +82,7 @@ def test_looks_like_provider_error_content():
def test_resolve_chat_stream_error_message_keeps_generic_without_probing():
- # Opaque upstream text must not be rewritten into an inferred API-key error.
+ # Sync helper must not probe — that stays in the async path.
assert (
resolve_chat_stream_error_message("An unknown error occurred.")
== "An unknown error occurred."
@@ -90,15 +90,132 @@ def test_resolve_chat_stream_error_message_keeps_generic_without_probing():
@pytest.mark.asyncio
-async def test_resolve_ingest_error_message_probes_credentials_on_disconnect(monkeypatch):
+async def test_resolve_chat_stream_error_message_async_probes_llm_on_generic(monkeypatch):
+ async def fake_llm_probe():
+ return (
+ "Model 'ibm/granite-4-h-small' was not found. "
+ "This model may be unsupported, deprecated, or removed."
+ )
+
+ async def fake_cred_probe():
+ raise AssertionError("must prefer LLM probe over credential probe")
+
+ monkeypatch.setattr(
+ "api.provider_validation.probe_chat_llm_error",
+ fake_llm_probe,
+ )
+ monkeypatch.setattr(
+ "api.provider_validation.probe_provider_credential_error",
+ fake_cred_probe,
+ )
+
+ from api.provider_validation import resolve_chat_stream_error_message_async
+
+ assert "granite-4-h-small" in await resolve_chat_stream_error_message_async(
+ "An unknown error occurred."
+ )
+
+
+async def test_resolve_chat_stream_error_message_async_falls_back_to_credentials(
+ monkeypatch,
+):
+ async def fake_llm_probe():
+ return None
+
+ async def fake_cred_probe():
+ return "Provided API key is disabled."
+
+ monkeypatch.setattr(
+ "api.provider_validation.probe_chat_llm_error",
+ fake_llm_probe,
+ )
+ monkeypatch.setattr(
+ "api.provider_validation.probe_provider_credential_error",
+ fake_cred_probe,
+ )
+
+ from api.provider_validation import resolve_chat_stream_error_message_async
+
+ assert (
+ await resolve_chat_stream_error_message_async("An unknown error occurred.")
+ == "Provided API key is disabled."
+ )
+
+
+async def test_resolve_chat_stream_error_message_async_keeps_specific_errors(monkeypatch):
async def fake_probe():
- return "Provided API key could not be found."
+ raise AssertionError("must not probe specific errors")
+ monkeypatch.setattr(
+ "api.provider_validation.probe_chat_llm_error",
+ fake_probe,
+ )
monkeypatch.setattr(
"api.provider_validation.probe_provider_credential_error",
fake_probe,
)
+ from api.provider_validation import resolve_chat_stream_error_message_async
+
+ assert (
+ await resolve_chat_stream_error_message_async("Rate limit exceeded")
+ == "Rate limit exceeded"
+ )
+
+
+async def test_probe_chat_llm_error_surfaces_missing_model(monkeypatch):
+ class FakeProvider:
+ def __init__(self):
+ self.api_key = "wx-ok"
+ self.endpoint = "https://us-south.ml.cloud.ibm.com"
+ self.project_id = "proj"
+
+ class FakeConfig:
+ class agent:
+ llm_provider = "watsonx"
+ llm_model = "ibm/granite-4-h-small"
+
+ def get_llm_provider_config(self):
+ return FakeProvider()
+
+ async def fake_validate(**kwargs):
+ assert kwargs.get("test_completion") is True
+ assert kwargs.get("llm_model") == "ibm/granite-4-h-small"
+ assert kwargs.get("embedding_model") is None
+ raise Exception(
+ "Model 'ibm/granite-4-h-small' was not found. "
+ "This model may be unsupported, deprecated, or removed."
+ )
+
+ monkeypatch.setattr("config.settings.get_openrag_config", lambda: FakeConfig())
+ monkeypatch.setattr("api.provider_validation.validate_provider_setup", fake_validate)
+
+ from api.provider_validation import probe_chat_llm_error
+
+ result = await probe_chat_llm_error()
+ assert result is not None
+ assert "granite-4-h-small" in result
+ assert "not found" in result.lower()
+
+
+async def test_resolve_ingest_error_message_probes_credentials_on_disconnect(monkeypatch):
+ async def fake_none():
+ return None
+
+ async def fake_cred_probe():
+ return "Provided API key could not be found."
+
+ monkeypatch.setattr("api.provider_validation.probe_embedding_error", fake_none)
+ monkeypatch.setattr("api.provider_validation.probe_chat_llm_error", fake_none)
+ monkeypatch.setattr(
+ "api.provider_validation.probe_provider_credential_error",
+ fake_cred_probe,
+ )
+
from api.provider_validation import resolve_ingest_error_message
assert (
@@ -112,6 +229,8 @@ async def test_resolve_ingest_error_message_keeps_disconnect_when_probe_clean(mo
async def fake_probe():
return None
+ monkeypatch.setattr("api.provider_validation.probe_embedding_error", fake_probe)
+ monkeypatch.setattr("api.provider_validation.probe_chat_llm_error", fake_probe)
monkeypatch.setattr(
"api.provider_validation.probe_provider_credential_error",
fake_probe,
@@ -123,6 +242,38 @@ async def test_resolve_ingest_error_message_keeps_disconnect_when_probe_clean(mo
assert await resolve_ingest_error_message(raw) == raw
+async def test_resolve_ingest_error_message_prefers_model_over_mislabeled_api_key(
+ monkeypatch,
+):
+ """Langflow often says API key invalid when the chat/LLM model is missing."""
+
+ async def fake_none():
+ return None
+
+ async def fake_llm_probe():
+ return (
+ "Model 'ibm/granite-4-h-small' was not found. "
+ "This model may be unsupported, deprecated, or removed."
+ )
+
+ async def fake_cred_probe():
+ raise AssertionError("credential probe must not run after LLM model diagnosis")
+
+ monkeypatch.setattr("api.provider_validation.probe_embedding_error", fake_none)
+ monkeypatch.setattr("api.provider_validation.probe_chat_llm_error", fake_llm_probe)
+ monkeypatch.setattr(
+ "api.provider_validation.probe_provider_credential_error",
+ fake_cred_probe,
+ )
+
+ from api.provider_validation import resolve_ingest_error_message
+
+ result = await resolve_ingest_error_message("API key is invalid")
+ assert "granite-4-h-small" in result
+ assert "not found" in result.lower()
+
+
@pytest.mark.asyncio
async def test_probe_checks_non_selected_providers_with_keys(monkeypatch):
"""Revoked watsonx must be detected even when openai is the selected provider."""
@@ -156,16 +307,11 @@ async def test_probe_checks_non_selected_providers_with_keys(monkeypatch):
async def fake_validate(**kwargs):
if kwargs.get("provider") == "watsonx":
- raise Exception(
- "Failed to authenticate with IBM Watson: Provided API key could not be found."
- )
+ raise Exception("Provided API key could not be found.")
monkeypatch.setattr("config.settings.get_openrag_config", lambda: FakeConfig())
monkeypatch.setattr("api.provider_validation.validate_provider_setup", fake_validate)
from api.provider_validation import probe_provider_credential_error
- assert (
- await probe_provider_credential_error()
- == "Failed to authenticate with IBM Watson: Provided API key could not be found."
- )
+ assert await probe_provider_credential_error() == "Provided API key is Invalid."
diff --git a/tests/unit/test_task_service_get_task_status2.py b/tests/unit/test_task_service_get_task_status2.py
index cbb76008a..159e194b0 100644
--- a/tests/unit/test_task_service_get_task_status2.py
+++ b/tests/unit/test_task_service_get_task_status2.py
@@ -170,6 +170,22 @@ class TestInferFailureMetadata:
assert meta["failure_phase"] == "unknown"
assert meta["actionable_by"] == "RETRYABLE"
+ def test_langflow_model_not_found_surfaces_specific_message(self, task_service):
+ ft = _make_file_task(
+ phase=IngestionPhase.LANGFLOW,
+ docling_status=DoclingPhaseStatus.SUCCESS,
+ error=(
+ "Model 'ibm/granite-4-h-small' was not found. "
+ "This model may be unsupported, deprecated, or removed."
+ ),
+ )
+ meta = task_service._infer_failure_metadata(ft)
+ assert meta is not None
+ assert meta["component"] == "langflow"
+ assert meta["actionable_by"] == "USER_ACTIONABLE"
+ assert "granite-4-h-small" in meta["user_facing_message"]
+ assert "unexpectedly" not in meta["user_facing_message"].lower()
+
def test_langflow_revoked_api_key_failure(self, task_service):
ft = _make_file_task(
phase=IngestionPhase.LANGFLOW,
@@ -332,6 +348,7 @@ class TestGetTaskStatus2FailureMetadata:
assert file_entry["component"] == "langflow"
assert file_entry["failure_phase"] == "unknown"
assert file_entry["actionable_by"] == "RETRYABLE"
+ assert file_entry["user_facing_message"] == "Langflow run failed"
def test_duplicate_file_failure_adds_metadata(self, task_service):
ft = _make_file_task(