diff --git a/ui/web/src/components/layout/background-error-banner.tsx b/ui/web/src/components/layout/background-error-banner.tsx
new file mode 100644
index 00000000..a706c994
--- /dev/null
+++ b/ui/web/src/components/layout/background-error-banner.tsx
@@ -0,0 +1,82 @@
+import { useState, useEffect, useCallback, useRef } from "react";
+import { useTranslation } from "react-i18next";
+import { AlertTriangle, X, Settings2 } from "lucide-react";
+import { useHttp } from "@/hooks/use-ws";
+import { useWsEvent } from "@/hooks/use-ws-event";
+import { useAuthStore } from "@/stores/use-auth-store";
+import { Button } from "@/components/ui/button";
+
+interface ProviderErrorPayload {
+ reason: string;
+ worker: string;
+ message: string;
+ timestamp: string;
+}
+
+interface BackgroundErrorBannerProps {
+ settingsOpen: boolean;
+ onOpenSettings: () => void;
+}
+
+export function BackgroundErrorBanner({ settingsOpen, onOpenSettings }: BackgroundErrorBannerProps) {
+ const { t } = useTranslation("system-settings");
+ const http = useHttp();
+ const role = useAuthStore((s) => s.role);
+ const isAdmin = role === "admin" || role === "owner";
+ const [error, setError] = useState
(null);
+ const [dismissed, setDismissed] = useState(false);
+
+ // Fetch alert state from the specific system config key.
+ const fetchAlert = useCallback(() => {
+ if (!isAdmin) return;
+ http.get<{ key: string; value: string }>("/v1/system-configs/alert.background.provider_error")
+ .then((res) => {
+ if (res.value) {
+ try { setError(JSON.parse(res.value)); } catch { /* ignore */ }
+ } else {
+ setError(null);
+ }
+ })
+ .catch(() => { setError(null); }); // 404 = no alert
+ }, [http, isAdmin]);
+
+ // Fetch on mount
+ useEffect(() => { fetchAlert(); }, [fetchAlert]);
+
+ // Re-fetch when settings modal closes (user may have fixed the issue)
+ const prevSettingsOpen = useRef(settingsOpen);
+ useEffect(() => {
+ if (prevSettingsOpen.current && !settingsOpen) fetchAlert();
+ prevSettingsOpen.current = settingsOpen;
+ }, [settingsOpen, fetchAlert]);
+
+ // Real-time WS event
+ useWsEvent("background.error", useCallback((payload: unknown) => {
+ setError(payload as ProviderErrorPayload);
+ setDismissed(false);
+ }, []));
+
+ if (!isAdmin || !error || dismissed) return null;
+
+ const reasonKey = `alert.reason.${error.reason}`;
+ const reasonText = t(reasonKey, { defaultValue: t("alert.reason.unknown") });
+
+ return (
+
+
+
+ {t("alert.message", { reason: reasonText })}
+
+
+
+