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.tsindex 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.tsindex 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.tsindex 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 providerconst 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 providerswitch (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.tsindex 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 specifiedif (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 failedconst 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 issuesconst 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 bannerreturn {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 succeededif (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 pollingif (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 30sconst 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.tsxindex 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.tsxindex 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 providedconst {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 changeuseUpdateSettings("anthropic",{- apiKey,+ apiKey: getFromEnv ? undefined : apiKey,+ clearApiKey: getFromEnv,languageModel,embeddingModel,},@@ -124,7 +121,7 @@ export function AnthropicOnboarding({<LabelInputlabel="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.tsxindex 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 providedconst {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 changeuseUpdateSettings("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><LabelWrapperlabel="Use environment watsonx API key"@@ -218,7 +237,7 @@ export function IBMOnboarding({<LabelInputlabel="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.tsxindex 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 changeuseUpdateSettings(@@ -120,8 +117,7 @@ export function OllamaOnboarding({)}{hasConnectionError && (<p className="text-mmd text-accent-amber-foreground">- Can'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.tsxindex 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 loopsconst 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 completionconst { 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 loopshandledFailedTasksRef.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 errorif (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"><AnthropicOnboardingsetSettings={setSettings}- setIsLoadingModels={setIsLoadingModels}isEmbedding={isEmbedding}hasEnvApiKey={currentSettings?.providers?.anthropic?.has_api_key ===@@ -685,7 +684,6 @@ const OnboardingCard = ({<TabsContent value="openai"><OpenAIOnboardingsetSettings={setSettings}- setIsLoadingModels={setIsLoadingModels}isEmbedding={isEmbedding}hasEnvApiKey={currentSettings?.providers?.openai?.has_api_key === true@@ -698,7 +696,6 @@ const OnboardingCard = ({<TabsContent value="watsonx"><IBMOnboardingsetSettings={setSettings}- setIsLoadingModels={setIsLoadingModels}isEmbedding={isEmbedding}alreadyConfigured={providerAlreadyConfigured && modelProvider === "watsonx"@@ -718,7 +715,6 @@ const OnboardingCard = ({<TabsContent value="ollama"><OllamaOnboardingsetSettings={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.tsxindex 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 providedconst {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 changeuseUpdateSettings("openai",{- apiKey,+ apiKey: getFromEnv || alreadyConfigured ? undefined : apiKey,+ clearApiKey: getFromEnv,languageModel,embeddingModel,},@@ -122,7 +116,7 @@ export function OpenAIOnboarding({<LabelInputlabel="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.tsindex 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/useOnboardingMutatinterface 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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 > 0diff --git a/frontend/lib/chat-stream-errors.test.ts b/frontend/lib/chat-stream-errors.test.tsindex 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.tsindex 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.tsindex 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.tsindex 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.pyindex 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.pyindex 9311f681d..5c884ad1e 100644--- a/src/api/models.py+++ b/src/api/models.py@@ -1,7 +1,14 @@+import re++import httpxfrom fastapi import Dependsfrom fastapi.responses import JSONResponsefrom pydantic import BaseModel+from api.provider_validation import (+ is_provider_credential_error,+ sanitize_provider_error_content,+)from config.settings import get_openrag_configfrom dependencies import get_models_service, require_permissionfrom session_manager import User@@ -9,6 +16,21 @@ from utils.logging_config import get_loggerlogger = 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.pyindex bc5aab9a7..dddaeb6bd 100644--- a/src/api/provider_health.py+++ b/src/api/provider_health.py@@ -6,7 +6,7 @@ import httpxfrom fastapi import Dependsfrom 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_setupfrom config.settings import get_openrag_configfrom dependencies import require_permissionfrom session_manager import User@@ -195,10 +195,10 @@ async def check_provider_health(llm_error = None # Don't treat as errorlogger.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 errorlogger.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.pyindex 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:+ continuelogger.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) -> Nologger.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 messageparsed_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 eraise@@ -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 messageparsed_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 eraise@@ -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) -> Nlogger.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.pyindex 748444ee5..3ea215467 100644--- a/src/api/settings/endpoints.py+++ b/src/api/settings/endpoints.py@@ -13,7 +13,7 @@ import jsonfrom fastapi import Depends, HTTPException, Requestfrom fastapi.responses import JSONResponse-from api.provider_validation import validate_provider_setup+from api.provider_validation import sanitize_provider_error_content, validate_provider_setupfrom 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.pyindex 0c498018b..e70ff9e87 100644--- a/src/services/models_service.py+++ b/src/services/models_service.py@@ -2,6 +2,7 @@ import asyncioimport httpx+from api.provider_validation import _extract_error_details, format_provider_error_messagefrom config.embedding_constants import OPENAI_DEFAULT_EMBEDDING_MODEL, OPENAI_EMBEDDING_MODEL_PREFIXfrom config.model_constants import (ANTHROPIC_DEFAULT_LANGUAGE_MODEL,@@ -284,9 +285,7 @@ class ModelsService:return resultelse: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 resultelse: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.pyindex 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.pyindex 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.pynew file mode 100644index 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"] == msgdiff --git a/tests/unit/test_provider_error_formatting.py b/tests/unit/test_provider_error_formatting.pyindex 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_messageassert (@@ -112,6 +229,8 @@ async def test_resolve_ingest_error_message_keeps_disconnect_when_probe_clean(moasync 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(moassert 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.asyncioasync 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.pyindex 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(