fix: improve codebase indexing error messages for better user experience

- Enhanced validation helpers to detect and format "fetch failed" errors with specific context
- Added Gemini-specific error handling with actionable guidance for common issues
- Improved orchestrator error messages to provide clearer troubleshooting information
- Enhanced Qdrant connection error messages with specific setup instructions
- Added new translation keys for better error messaging

Fixes #5801

apps/web-evals/next.config.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var nextConfig = {
+    webpack: function (config) {
+        config.resolve.extensionAlias = { ".js": [".ts", ".tsx", ".js", ".jsx"] };
+        return config;
+    },
+};
+exports.default = nextConfig;

apps/web-evals/src/actions/exercises.js

@@ -0,0 +1,69 @@
+"use server";
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getExercises = void 0;
+var path = require("path");
+var url_1 = require("url");
+var evals_1 = require("@roo-code/evals");
+var __dirname = path.dirname((0, url_1.fileURLToPath)(import.meta.url)); // <repo>/apps/web-evals/src/actions
+var EVALS_REPO_PATH = path.resolve(__dirname, "../../../../../evals");
+var getExercises = function () { return __awaiter(void 0, void 0, void 0, function () {
+    var result;
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0: return [4 /*yield*/, Promise.all(evals_1.exerciseLanguages.map(function (language) { return __awaiter(void 0, void 0, void 0, function () {
+                    var languagePath, exercises;
+                    return __generator(this, function (_a) {
+                        switch (_a.label) {
+                            case 0:
+                                languagePath = path.join(EVALS_REPO_PATH, language);
+                                return [4 /*yield*/, (0, evals_1.listDirectories)(__dirname, languagePath)];
+                            case 1:
+                                exercises = _a.sent();
+                                return [2 /*return*/, exercises.map(function (exercise) { return "".concat(language, "/").concat(exercise); })];
+                        }
+                    });
+                }); }))];
+            case 1:
+                result = _a.sent();
+                return [2 /*return*/, result.flat()];
+        }
+    });
+}); };
+exports.getExercises = getExercises;

apps/web-evals/vitest.config.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var config_1 = require("vitest/config");
+exports.default = (0, config_1.defineConfig)({
+    test: {
+        globals: true,
+        watch: false,
+    },
+});

src/i18n/locales/en/embeddings.json

@@ -39,7 +39,10 @@
 		"invalidModel": "Invalid model. Please check your model configuration.",
 		"invalidResponse": "Invalid response from embedder service. Please check your configuration.",
 		"apiKeyRequired": "API key is required for this embedder",
-		"baseUrlRequired": "Base URL is required for this embedder"
+		"baseUrlRequired": "Base URL is required for this embedder",
+		"fetchFailed": "Network request failed: {{details}}. Please check your internet connection and service availability.",
+		"sslError": "SSL/TLS certificate error. Please check your connection security settings or contact your network administrator.",
+		"dnsError": "DNS resolution failed. Please check your internet connection and verify the service URL is correct."
 	},
 	"serviceFactory": {
 		"openAiConfigMissing": "OpenAI configuration missing for embedder creation",

src/services/code-index/embedders/gemini.ts

@@ -70,7 +70,41 @@ export class GeminiEmbedder implements IEmbedder {
 		try {
 			// Delegate validation to the OpenAI-compatible embedder
 			// The error messages will be specific to Gemini since we're using Gemini's base URL
-			return await this.openAICompatibleEmbedder.validateConfiguration()
+			const result = await this.openAICompatibleEmbedder.validateConfiguration()
+			
+			// If validation failed, enhance the error message with Gemini-specific context
+			if (!result.valid && result.error) {
+				// Check for common Gemini-specific issues
+				if (result.error.includes("fetch failed") || result.error.includes("Network request failed")) {
+					return {
+						valid: false,
+						error: t("embeddings:validation.connectionFailed") + " Please verify your Gemini API key is valid and you have internet connectivity to Google's services."
+					}
+				}
+				
+				if (result.error.includes("Authentication failed") || result.error.includes("401")) {
+					return {
+						valid: false,
+						error: "Invalid Gemini API key. Please check your API key in Google AI Studio (https://aistudio.google.com/app/apikey) and ensure it's correctly entered in the settings."
+					}
+				}
+				
+				if (result.error.includes("403")) {
+					return {
+						valid: false,
+						error: "Access denied to Gemini API. Please ensure your API key has the necessary permissions and your account has access to the embedding models."
+					}
+				}
+				
+				if (result.error.includes("404")) {
+					return {
+						valid: false,
+						error: `Gemini model '${this.modelId}' not found. Please verify the model ID is correct and available in your region.`
+					}
+				}
+			}
+			
+			return result
 		} catch (error) {
 			TelemetryService.instance.captureEvent(TelemetryEventName.CODE_INDEX_ERROR, {
 				error: error instanceof Error ? error.message : String(error),

src/services/code-index/orchestrator.ts

@@ -219,7 +219,32 @@ export class CodeIndexOrchestrator {
 
 			await this.cacheManager.clearCacheFile()
 
-			this.stateManager.setSystemState("Error", `Failed during initial scan: ${error.message || "Unknown error"}`)
+			// Provide more detailed error messages based on the error type
+			let errorMessage = "Unknown error"
+			if (error instanceof Error) {
+				errorMessage = error.message
+				
+				// Check for specific error patterns and provide more helpful messages
+				if (errorMessage.includes("fetch failed")) {
+					errorMessage = "Network connection failed. Please check your internet connection and verify that the embedding service (Gemini, OpenAI, etc.) is accessible."
+				} else if (errorMessage.includes("ECONNREFUSED")) {
+					errorMessage = "Connection refused. Please ensure Qdrant is running at the configured URL and check your firewall settings."
+				} else if (errorMessage.includes("ENOTFOUND")) {
+					errorMessage = "Service not found. Please verify the URLs for both your embedding service and Qdrant are correct."
+				} else if (errorMessage.includes("Authentication failed") || errorMessage.includes("401")) {
+					errorMessage = "Authentication failed. Please check your API key configuration."
+				} else if (errorMessage.includes("403")) {
+					errorMessage = "Access denied. Please verify your API key has the necessary permissions."
+				} else if (errorMessage.includes("404")) {
+					errorMessage = "Service or model not found. Please check your configuration settings."
+				} else if (errorMessage.includes("Failed to connect to Qdrant")) {
+					errorMessage = "Cannot connect to Qdrant vector database. Please ensure Qdrant is running and accessible."
+				} else if (errorMessage.includes("vector dimension")) {
+					errorMessage = "Vector dimension mismatch. Please clear the index and try again, or check your model configuration."
+				}
+			}
+
+			this.stateManager.setSystemState("Error", `Failed during initial scan: ${errorMessage}`)
 			this.stopWatcher()
 		} finally {
 			this._isProcessing = false

src/services/code-index/shared/validation-helpers.ts

@@ -183,6 +183,29 @@ export function handleValidationError(
 			return { valid: false, error: t("embeddings:validation.connectionFailed") }
 		}
 
+		// Handle "fetch failed" errors with more specific context
+		if (errorMessage.includes("fetch failed")) {
+			// Check if it's likely a network connectivity issue
+			if (errorMessage.includes("ECONNREFUSED") || errorMessage.includes("ENOTFOUND")) {
+				return { valid: false, error: t("embeddings:validation.connectionFailed") }
+			}
+			// Check if it's likely an SSL/TLS issue
+			if (errorMessage.includes("certificate") || errorMessage.includes("SSL") || errorMessage.includes("TLS")) {
+				return { valid: false, error: t("embeddings:validation.sslError") }
+			}
+			// Check if it's likely a DNS issue
+			if (errorMessage.includes("getaddrinfo") || errorMessage.includes("ENOTFOUND")) {
+				return { valid: false, error: t("embeddings:validation.dnsError") }
+			}
+			// Generic fetch failed error with more helpful message
+			return {
+				valid: false,
+				error: t("embeddings:validation.fetchFailed", {
+					details: sanitizeErrorMessage(errorMessage)
+				})
+			}
+		}
+
 		if (errorMessage.includes("Failed to parse response JSON")) {
 			return { valid: false, error: t("embeddings:validation.invalidResponse") }
 		}

src/services/code-index/vector-store/qdrant-client.ts

@@ -199,10 +199,28 @@ export class QdrantVectorStore implements IVectorStore {
 				throw error
 			}
 
+			// Provide more specific error messages based on the error type
+			let userFriendlyMessage = ""
+			if (typeof errorMessage === "string") {
+				if (errorMessage.includes("fetch failed") || errorMessage.includes("ECONNREFUSED")) {
+					userFriendlyMessage = `Cannot connect to Qdrant at ${this.qdrantUrl}. Please ensure Qdrant is running and accessible. If using Docker, verify the container is started with: docker run -p 6333:6333 qdrant/qdrant`
+				} else if (errorMessage.includes("ENOTFOUND")) {
+					userFriendlyMessage = `Qdrant server not found at ${this.qdrantUrl}. Please check the URL is correct and the server is running.`
+				} else if (errorMessage.includes("ETIMEDOUT")) {
+					userFriendlyMessage = `Connection to Qdrant at ${this.qdrantUrl} timed out. Please check your network connection and firewall settings.`
+				} else if (errorMessage.includes("401") || errorMessage.includes("403")) {
+					userFriendlyMessage = `Authentication failed for Qdrant at ${this.qdrantUrl}. Please check your API key configuration.`
+				} else if (errorMessage.includes("404")) {
+					userFriendlyMessage = `Qdrant endpoint not found at ${this.qdrantUrl}. Please verify the URL is correct.`
+				} else {
+					userFriendlyMessage = t("embeddings:vectorStore.qdrantConnectionFailed", { qdrantUrl: this.qdrantUrl, errorMessage })
+				}
+			} else {
+				userFriendlyMessage = t("embeddings:vectorStore.qdrantConnectionFailed", { qdrantUrl: this.qdrantUrl, errorMessage })
+			}
+
 			// Otherwise, provide a more user-friendly error message that includes the original error
-			throw new Error(
-				t("embeddings:vectorStore.qdrantConnectionFailed", { qdrantUrl: this.qdrantUrl, errorMessage }),
-			)
+			throw new Error(userFriendlyMessage)
 		}
 	}