Merge pull request #617 from langflow-ai/fix/onboarding_rollback

fix: adds onboarding rollback to allow user to edit embedding provider if ingestion fails

frontend/app/api/mutations/useOnboardingRollbackMutation.ts

@@ -0,0 +1,44 @@
+import {
+  type UseMutationOptions,
+  useMutation,
+  useQueryClient,
+} from "@tanstack/react-query";
+
+interface OnboardingRollbackResponse {
+  message: string;
+}
+
+export const useOnboardingRollbackMutation = (
+  options?: Omit<
+    UseMutationOptions<OnboardingRollbackResponse, Error, void>,
+    "mutationFn"
+  >,
+) => {
+  const queryClient = useQueryClient();
+
+  async function rollbackOnboarding(): Promise<OnboardingRollbackResponse> {
+    const response = await fetch("/api/onboarding/rollback", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      throw new Error(error.error || "Failed to rollback onboarding");
+    }
+
+    return response.json();
+  }
+
+  return useMutation({
+    mutationFn: rollbackOnboarding,
+    onSettled: () => {
+      // Invalidate settings query to refetch updated data
+      queryClient.invalidateQueries({ queryKey: ["settings"] });
+    },
+    ...options,
+  });
+};
+

frontend/app/onboarding/_components/onboarding-card.tsx

@@ -3,12 +3,13 @@
 import { useQueryClient } from "@tanstack/react-query";
 import { AnimatePresence, motion } from "framer-motion";
 import { X } from "lucide-react";
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { toast } from "sonner";
 import {
   type OnboardingVariables,
   useOnboardingMutation,
 } from "@/app/api/mutations/useOnboardingMutation";
+import { useOnboardingRollbackMutation } from "@/app/api/mutations/useOnboardingRollbackMutation";
 import { useGetSettingsQuery } from "@/app/api/queries/useGetSettingsQuery";
 import { useGetTasksQuery } from "@/app/api/queries/useGetTasksQuery";
 import type { ProviderHealthResponse } from "@/app/api/queries/useProviderHealthQuery";
@@ -170,12 +171,32 @@ const OnboardingCard = ({
 
   const [error, setError] = useState<string | null>(null);
 
+  // Track which tasks we've already handled to prevent infinite loops
+  const handledFailedTasksRef = useRef<Set<string>>(new Set());
+
   // Query tasks to track completion
   const { data: tasks } = useGetTasksQuery({
     enabled: currentStep !== null, // Only poll when onboarding has started
     refetchInterval: currentStep !== null ? 1000 : false, // Poll every 1 second during onboarding
   });
 
+  // Rollback mutation
+  const rollbackMutation = useOnboardingRollbackMutation({
+    onSuccess: () => {
+      console.log("Onboarding rolled back successfully");
+      // Reset to provider selection step
+      // Error message is already set before calling mutate
+      setCurrentStep(null);
+    },
+    onError: (error) => {
+      console.error("Failed to rollback onboarding", error);
+      // Preserve existing error message if set, otherwise show rollback error
+      setError((prevError) => prevError || `Failed to rollback: ${error.message}`);
+      // Still reset to provider selection even if rollback fails
+      setCurrentStep(null);
+    },
+  });
+
   // Monitor tasks and call onComplete when all tasks are done
   useEffect(() => {
     if (currentStep === null || !tasks || !isEmbedding) {
@@ -190,11 +211,86 @@ const OnboardingCard = ({
         task.status === "processing",
     );
 
+    // Check if any file failed in completed tasks
+    const completedTasks = tasks.filter(
+      (task) => task.status === "completed"
+    );
+
+    // Check if any completed task has at least one failed file
+    const taskWithFailedFile = completedTasks.find((task) => {
+      // Must have files object
+      if (!task.files || typeof task.files !== "object") {
+        return false;
+      }
+
+      const fileEntries = Object.values(task.files);
+      
+      // Must have at least one file
+      if (fileEntries.length === 0) {
+        return false;
+      }
+
+      // Check if any file has failed status
+      const hasFailedFile = fileEntries.some(
+        (file) => file.status === "failed" || file.status === "error"
+      );
+
+      return hasFailedFile;
+    });
+
+    // If any file failed, show error and jump back one step (like onboardingMutation.onError)
+    // Only handle if we haven't already handled this task
+    if (
+      taskWithFailedFile && 
+      !rollbackMutation.isPending && 
+      !isCompleted &&
+      !handledFailedTasksRef.current.has(taskWithFailedFile.task_id)
+    ) {
+      console.error("File failed in task, jumping back one step", taskWithFailedFile);
+      
+      // Mark this task as handled to prevent infinite loops
+      handledFailedTasksRef.current.add(taskWithFailedFile.task_id);
+      
+      // Extract error messages from failed files
+      const errorMessages: string[] = [];
+      if (taskWithFailedFile.files) {
+        Object.values(taskWithFailedFile.files).forEach((file) => {
+          if ((file.status === "failed" || file.status === "error") && file.error) {
+            errorMessages.push(file.error);
+          }
+        });
+      }
+      
+      // Also check task-level error
+      if (taskWithFailedFile.error) {
+        errorMessages.push(taskWithFailedFile.error);
+      }
+      
+      // Use the first error message, or a generic message if no errors found
+      const errorMessage = errorMessages.length > 0
+        ? errorMessages[0]
+        : "Sample data file failed to ingest. Please try again with a different configuration.";
+      
+      // Set error message and jump back one step (exactly like onboardingMutation.onError)
+      setError(errorMessage);
+      setCurrentStep(totalSteps);
+      // Jump back one step after 1 second (go back to the step before ingestion)
+      // For embedding: totalSteps is 4, ingestion is step 3, so go back to step 2
+      // For LLM: totalSteps is 3, ingestion is step 2, so go back to step 1
+      setTimeout(() => {
+        // Go back to the step before the last step (which is ingestion)
+        const previousStep = totalSteps > 1 ? totalSteps - 2 : 0;
+        setCurrentStep(previousStep);
+      }, 1000);
+      return;
+    }
+
     // If no active tasks and we've started onboarding, complete it
     if (
       (!activeTasks || (activeTasks.processed_files ?? 0) > 0) &&
       tasks.length > 0 &&
-      !isCompleted
+      !isCompleted &&
+      !taskWithFailedFile
     ) {
       // Set to final step to show "Done"
       setCurrentStep(totalSteps);
@@ -203,7 +299,7 @@ const OnboardingCard = ({
         onComplete();
       }, 1000);
     }
-  }, [tasks, currentStep, onComplete, isCompleted, isEmbedding, totalSteps]);
+  }, [tasks, currentStep, onComplete, isCompleted, isEmbedding, totalSteps, rollbackMutation]);
 
   // Mutations
   const onboardingMutation = useOnboardingMutation({

frontend/contexts/chat-context.tsx

@@ -11,6 +11,7 @@ import {
   useState,
 } from "react";
 import { ONBOARDING_STEP_KEY } from "@/lib/constants";
+import { useGetSettingsQuery } from "@/app/api/queries/useGetSettingsQuery";
 
 export type EndpointType = "chat" | "langflow";
 
@@ -115,23 +116,32 @@ export function ChatProvider({ children }: ChatProviderProps) {
     useState<KnowledgeFilter | null>(null);
   const [hasChatError, setChatError] = useState(false);
   
-  // Check if onboarding is complete (onboarding step key should be null)
+  // Get settings to check if onboarding was completed (settings.edited)
+  const { data: settings } = useGetSettingsQuery();
+  
+  // Check if onboarding is complete
+  // Onboarding is complete if:
+  // 1. settings.edited is true (backend confirms onboarding was completed)
+  // 2. AND onboarding step key is null (local onboarding flow is done)
   const [isOnboardingComplete, setIsOnboardingComplete] = useState(() => {
     if (typeof window === "undefined") return false;
-    return localStorage.getItem(ONBOARDING_STEP_KEY) === null;
+    // Default to false if settings not loaded yet
+    return false;
   });
 
-  // Sync onboarding completion state with localStorage
+  // Sync onboarding completion state with settings.edited and localStorage
   useEffect(() => {
     const checkOnboarding = () => {
       if (typeof window !== "undefined") {
-        setIsOnboardingComplete(
-          localStorage.getItem(ONBOARDING_STEP_KEY) === null,
-        );
+        // Onboarding is complete if settings.edited is true AND step key is null
+        const stepKeyExists = localStorage.getItem(ONBOARDING_STEP_KEY) !== null;
+        const isEdited = settings?.edited === true;
+        // Complete if edited is true and step key doesn't exist (onboarding flow finished)
+        setIsOnboardingComplete(isEdited && !stepKeyExists);
       }
     };
 
-    // Check on mount
+    // Check on mount and when settings change
     checkOnboarding();
 
     // Listen for storage events (for cross-tab sync)
@@ -140,7 +150,7 @@ export function ChatProvider({ children }: ChatProviderProps) {
     return () => {
       window.removeEventListener("storage", checkOnboarding);
     };
-  }, []);
+  }, [settings?.edited]);
 
   const setOnboardingComplete = useCallback((complete: boolean) => {
     setIsOnboardingComplete(complete);

src/api/settings.py

@@ -897,7 +897,7 @@ async def onboarding(request, flows_service, session_manager=None):
             )
 
         # Validate provider setup before initializing OpenSearch index
-        # Use lightweight validation (test_completion=False) to avoid consuming credits during onboarding
+        # Use full validation with completion tests (test_completion=True) to ensure provider health during onboarding
         try:
             from api.provider_validation import validate_provider_setup
 
@@ -906,14 +906,14 @@ async def onboarding(request, flows_service, session_manager=None):
                 llm_provider = current_config.agent.llm_provider.lower()
                 llm_provider_config = current_config.get_llm_provider_config()
 
-                logger.info(f"Validating LLM provider setup for {llm_provider} (lightweight)")
+                logger.info(f"Validating LLM provider setup for {llm_provider} (full validation with completion test)")
                 await validate_provider_setup(
                     provider=llm_provider,
                     api_key=getattr(llm_provider_config, "api_key", None),
                     llm_model=current_config.agent.llm_model,
                     endpoint=getattr(llm_provider_config, "endpoint", None),
                     project_id=getattr(llm_provider_config, "project_id", None),
-                    test_completion=False,  # Lightweight validation - no credits consumed
+                    test_completion=True,  # Full validation with completion test - ensures provider health
                 )
                 logger.info(f"LLM provider setup validation completed successfully for {llm_provider}")
 
@@ -922,14 +922,14 @@ async def onboarding(request, flows_service, session_manager=None):
                 embedding_provider = current_config.knowledge.embedding_provider.lower()
                 embedding_provider_config = current_config.get_embedding_provider_config()
 
-                logger.info(f"Validating embedding provider setup for {embedding_provider} (lightweight)")
+                logger.info(f"Validating embedding provider setup for {embedding_provider} (full validation with completion test)")
                 await validate_provider_setup(
                     provider=embedding_provider,
                     api_key=getattr(embedding_provider_config, "api_key", None),
                     embedding_model=current_config.knowledge.embedding_model,
                     endpoint=getattr(embedding_provider_config, "endpoint", None),
                     project_id=getattr(embedding_provider_config, "project_id", None),
-                    test_completion=False,  # Lightweight validation - no credits consumed
+                    test_completion=True,  # Full validation with completion test - ensures provider health
                 )
                 logger.info(f"Embedding provider setup validation completed successfully for {embedding_provider}")
         except Exception as e:
@@ -1403,6 +1403,139 @@ async def reapply_all_settings(session_manager = None):
         raise
 
 
+async def rollback_onboarding(request, session_manager, task_service):
+    """Rollback onboarding configuration when sample data files fail.
+    
+    This will:
+    1. Cancel all active tasks
+    2. Delete successfully ingested knowledge documents
+    3. Reset configuration to allow re-onboarding
+    """
+    try:
+        # Get current configuration
+        current_config = get_openrag_config()
+
+        # Only allow rollback if config was marked as edited (onboarding completed)
+        if not current_config.edited:
+            return JSONResponse(
+                {"error": "No onboarding configuration to rollback"}, status_code=400
+            )
+
+        user = request.state.user
+        jwt_token = session_manager.get_effective_jwt_token(user.user_id, request.state.jwt_token)
+
+        logger.info("Rolling back onboarding configuration due to file failures")
+
+        # Get all tasks for the user
+        all_tasks = task_service.get_all_tasks(user.user_id)
+        
+        cancelled_tasks = []
+        deleted_files = []
+        
+        # Cancel all active tasks and collect successfully ingested files
+        for task_data in all_tasks:
+            task_id = task_data.get("task_id")
+            task_status = task_data.get("status")
+            
+            # Cancel active tasks (pending, running, processing)
+            if task_status in ["pending", "running", "processing"]:
+                try:
+                    success = await task_service.cancel_task(user.user_id, task_id)
+                    if success:
+                        cancelled_tasks.append(task_id)
+                        logger.info(f"Cancelled task {task_id}")
+                except Exception as e:
+                    logger.error(f"Failed to cancel task {task_id}: {str(e)}")
+            
+            # For completed tasks, find successfully ingested files and delete them
+            elif task_status == "completed":
+                files = task_data.get("files", {})
+                if isinstance(files, dict):
+                    for file_path, file_info in files.items():
+                        # Check if file was successfully ingested
+                        if isinstance(file_info, dict):
+                            file_status = file_info.get("status")
+                            filename = file_info.get("filename") or file_path.split("/")[-1]
+                            
+                            if file_status == "completed" and filename:
+                                try:
+                                    # Get user's OpenSearch client
+                                    opensearch_client = session_manager.get_user_opensearch_client(
+                                        user.user_id, jwt_token
+                                    )
+                                    
+                                    # Delete documents by filename
+                                    from utils.opensearch_queries import build_filename_delete_body
+                                    from config.settings import INDEX_NAME
+                                    
+                                    delete_query = build_filename_delete_body(filename)
+                                    
+                                    result = await opensearch_client.delete_by_query(
+                                        index=INDEX_NAME,
+                                        body=delete_query,
+                                        conflicts="proceed"
+                                    )
+                                    
+                                    deleted_count = result.get("deleted", 0)
+                                    if deleted_count > 0:
+                                        deleted_files.append(filename)
+                                        logger.info(f"Deleted {deleted_count} chunks for filename {filename}")
+                                except Exception as e:
+                                    logger.error(f"Failed to delete documents for {filename}: {str(e)}")
+
+        # Clear embedding provider and model settings
+        current_config.knowledge.embedding_provider = "openai"  # Reset to default
+        current_config.knowledge.embedding_model = ""
+        
+        # Mark config as not edited so user can go through onboarding again
+        current_config.edited = False
+
+        # Save the rolled back configuration manually to avoid save_config_file setting edited=True
+        try:
+            import yaml
+            config_file = config_manager.config_file
+            
+            # Ensure directory exists
+            config_file.parent.mkdir(parents=True, exist_ok=True)
+            
+            # Save config with edited=False
+            with open(config_file, "w") as f:
+                yaml.dump(current_config.to_dict(), f, default_flow_style=False, indent=2)
+            
+            # Update cached config
+            config_manager._config = current_config
+            
+            logger.info("Successfully saved rolled back configuration with edited=False")
+        except Exception as e:
+            logger.error(f"Failed to save rolled back configuration: {e}")
+            return JSONResponse(
+                {"error": "Failed to save rolled back configuration"}, status_code=500
+            )
+
+        logger.info(
+            f"Successfully rolled back onboarding configuration. "
+            f"Cancelled {len(cancelled_tasks)} tasks, deleted {len(deleted_files)} files"
+        )
+        await TelemetryClient.send_event(
+            Category.ONBOARDING, 
+            MessageId.ORB_ONBOARD_ROLLBACK
+        )
+        
+        return JSONResponse(
+            {
+                "message": "Onboarding configuration rolled back successfully",
+                "cancelled_tasks": len(cancelled_tasks),
+                "deleted_files": len(deleted_files),
+            }
+        )
+
+    except Exception as e:
+        logger.error("Failed to rollback onboarding configuration", error=str(e))
+        return JSONResponse(
+            {"error": f"Failed to rollback onboarding: {str(e)}"}, status_code=500
+        )
+
+
 async def update_docling_preset(request, session_manager):
     """Update docling settings in the ingest flow - deprecated endpoint, use /settings instead"""
     try:

src/main.py

@@ -1179,6 +1179,18 @@ async def create_app():
             ),
             methods=["POST"],
         ),
+        # Onboarding rollback endpoint
+        Route(
+            "/onboarding/rollback",
+            require_auth(services["session_manager"])(
+                partial(
+                    settings.rollback_onboarding,
+                    session_manager=services["session_manager"],
+                    task_service=services["task_service"],
+                )
+            ),
+            methods=["POST"],
+        ),
         # Docling preset update endpoint
         Route(
             "/settings/docling-preset",

src/utils/telemetry/message_id.py

@@ -199,3 +199,5 @@ class MessageId:
     ORB_ONBOARD_SAMPLE_DATA = "ORB_ONBOARD_SAMPLE_DATA"
     # Message: Configuration marked as edited
     ORB_ONBOARD_CONFIG_EDITED = "ORB_ONBOARD_CONFIG_EDITED"
+    # Message: Onboarding rolled back due to all files failing
+    ORB_ONBOARD_ROLLBACK = "ORB_ONBOARD_ROLLBACK"