feat: improve Code Index error messages with detailed context

- Enhanced error messages in validation-helpers.ts to provide specific context
- Added detailed error translations in embeddings.json
- Improved error handling in manager.ts with contextual hints
- Enhanced service-factory.ts validation error reporting
- Updated OpenAI and OpenAI-compatible embedders with better error context
- Fixed tests to match new error message format

Addresses #8015

Author: roomote

src/i18n/locales/en/embeddings.json

@@ -1,11 +1,13 @@
 {
 	"unknownError": "Unknown error",
-	"authenticationFailed": "Failed to create embeddings: Authentication failed. Please check your API key.",
-	"failedWithStatus": "Failed to create embeddings after {{attempts}} attempts: HTTP {{statusCode}} - {{errorMessage}}",
+	"authenticationFailed": "Failed to create embeddings: Authentication failed for {{provider}}. Please check your API key.",
+	"failedWithStatus": "Failed to create embeddings after {{attempts}} attempts with {{provider}}: HTTP {{statusCode}} - {{errorMessage}}",
 	"failedWithError": "Failed to create embeddings after {{attempts}} attempts: {{errorMessage}}",
 	"failedMaxAttempts": "Failed to create embeddings after {{attempts}} attempts",
 	"textExceedsTokenLimit": "Text at index {{index}} exceeds maximum token limit ({{itemTokens}} > {{maxTokens}}). Skipping.",
 	"rateLimitRetry": "Rate limit hit, retrying in {{delayMs}}ms (attempt {{attempt}}/{{maxRetries}})",
+	"rateLimitExhausted": "Rate limit exceeded for {{provider}} after {{attempts}} attempts. Please wait before retrying or check your API plan limits.",
+	"textWithPrefixExceedsTokenLimit": "Text at index {{index}} with query prefix exceeds maximum token limit ({{estimatedTokens}} > {{maxTokens}}). Using original text without prefix.",
 	"ollama": {
 		"couldNotReadErrorBody": "Could not read error body",
 		"requestFailed": "Ollama API request failed with status {{status}} {{statusText}}: {{errorBody}}",
@@ -27,40 +29,68 @@
 		"vectorDimensionMismatch": "Failed to update vector index for new model. Please try clearing the index and starting again. Details: {{errorMessage}}"
 	},
 	"validation": {
-		"authenticationFailed": "Authentication failed. Please check your API key in the settings.",
+		"authenticationFailed": "Authentication failed for {{provider}}. Please check your API key in the settings.",
 		"connectionFailed": "Failed to connect to the embedder service. Please check your connection settings and ensure the service is running.",
-		"modelNotAvailable": "The specified model is not available. Please check your model configuration.",
-		"configurationError": "Invalid embedder configuration. Please review your settings.",
+		"modelNotAvailable": "Model '{{modelId}}' is not available. Please verify the model exists and you have access to it.",
+		"configurationError": "Invalid configuration for {{provider}}. Please review your settings.",
 		"serviceUnavailable": "The embedder service is not available. Please ensure it is running and accessible.",
-		"invalidEndpoint": "Invalid API endpoint. Please check your URL configuration.",
+		"invalidEndpoint": "Invalid API endpoint{{#if endpoint}}: {{endpoint}}{{/if}}. Please check your URL configuration.",
 		"invalidEmbedderConfig": "Invalid embedder configuration. Please check your settings.",
 		"invalidApiKey": "Invalid API key. Please check your API key configuration.",
 		"invalidBaseUrl": "Invalid base URL. Please check your URL configuration.",
 		"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",
+		"badRequest": "Bad request to {{provider}}{{#if endpoint}} at {{endpoint}}{{/if}}. Please check your configuration and request parameters.",
+		"forbidden": "Access forbidden for {{provider}}. Please check your API key permissions and account status.",
+		"rateLimitExceeded": "Rate limit exceeded for {{provider}}. Please wait before retrying or upgrade your API plan.",
+		"serverError": "Server error from {{provider}} (HTTP {{status}}). The service may be experiencing issues. Please try again later.",
+		"notImplemented": "The endpoint{{#if endpoint}} {{endpoint}}{{/if}} does not support embeddings. Please check if you're using the correct endpoint URL.",
+		"clientError": "Client error with {{provider}} (HTTP {{status}}). Please check your configuration.",
+		"hostNotFound": "Cannot resolve host{{#if endpoint}} for {{endpoint}}{{/if}}. Please check the URL and your network connection.",
+		"connectionRefused": "Connection refused{{#if endpoint}} to {{endpoint}}{{/if}}. Please ensure the service is running and accessible.",
+		"connectionTimeout": "Connection timeout{{#if endpoint}} to {{endpoint}}{{/if}}. The service may be slow or unreachable.",
+		"noResponse": "No response received from {{provider}}. Please check your network connection.",
+		"invalidResponseFormat": "Invalid response format from {{provider}}. The endpoint may not be compatible with the expected API format.",
+		"apiKeyIssue": "API key issue with {{provider}}{{#if source}} (configured in {{source}}){{/if}}. Please verify your API key is correct and has the necessary permissions.",
+		"modelIssue": "Model issue with {{provider}}{{#if modelId}} for model '{{modelId}}'{{/if}}. Please verify the model is available and supports embeddings.",
+		"dimensionMismatch": "Vector dimension mismatch{{#if modelId}} for model '{{modelId}}'{{/if}}. The model's embedding dimensions don't match the existing index.",
+		"unexpectedError": "Unexpected error with {{provider}}. Please check the logs for more details.",
+		"checkNetworkAndVPN": "Check your network connection and VPN settings if applicable.",
+		"checkServiceRunning": "Ensure the service is running and the port is not blocked by a firewall.",
+		"checkFirewallProxy": "Check firewall settings and proxy configuration if behind a corporate network.",
+		"checkNetworkStability": "Check your network stability and try again.",
+		"checkEndpointCompatibility": "Verify the endpoint is compatible with OpenAI's embedding API format.",
+		"clearIndexAndRestart": "Try clearing the index and restarting with the new model configuration.",
+		"checkApiKeyInSettings": "Please verify your API key in Settings > Code Index.",
+		"checkEndpointAndModel": "Please verify the endpoint URL and model '{{modelId}}' are correct.",
+		"checkServiceAndNetwork": "Please ensure the service is running and check your network connection."
 	},
 	"serviceFactory": {
-		"openAiConfigMissing": "OpenAI configuration missing for embedder creation",
-		"ollamaConfigMissing": "Ollama configuration missing for embedder creation",
-		"openAiCompatibleConfigMissing": "OpenAI Compatible configuration missing for embedder creation",
-		"geminiConfigMissing": "Gemini configuration missing for embedder creation",
-		"mistralConfigMissing": "Mistral configuration missing for embedder creation",
-		"vercelAiGatewayConfigMissing": "Vercel AI Gateway configuration missing for embedder creation",
-		"invalidEmbedderType": "Invalid embedder type configured: {{embedderProvider}}",
+		"openAiConfigMissing": "OpenAI configuration missing. Please provide an API key in the Code Index settings.",
+		"ollamaConfigMissing": "Ollama configuration missing. Please provide the Ollama base URL in the Code Index settings.",
+		"openAiCompatibleConfigMissing": "OpenAI Compatible configuration missing. Please provide both base URL and API key in the Code Index settings.",
+		"geminiConfigMissing": "Gemini configuration missing. Please provide an API key in the Code Index settings.",
+		"mistralConfigMissing": "Mistral configuration missing. Please provide an API key in the Code Index settings.",
+		"vercelAiGatewayConfigMissing": "Vercel AI Gateway configuration missing. Please provide an API key in the Code Index settings.",
+		"invalidEmbedderType": "Invalid embedder type configured: '{{embedderProvider}}'. Please select a valid provider in the Code Index settings.",
 		"vectorDimensionNotDeterminedOpenAiCompatible": "Could not determine vector dimension for model '{{modelId}}' with provider '{{provider}}'. Please ensure the 'Embedding Dimension' is correctly set in the OpenAI-Compatible provider settings.",
 		"vectorDimensionNotDetermined": "Could not determine vector dimension for model '{{modelId}}' with provider '{{provider}}'. Check model profiles or configuration.",
-		"qdrantUrlMissing": "Qdrant URL missing for vector store creation",
-		"codeIndexingNotConfigured": "Cannot create services: Code indexing is not properly configured"
+		"qdrantUrlMissing": "Qdrant URL missing. Please configure the Qdrant vector database URL in the Code Index settings.",
+		"codeIndexingNotConfigured": "Code indexing is not properly configured. Please complete the setup in Settings > Code Index.",
+		"embeddingValidationFailed": "Failed to validate {{provider}} embedder: {{error}}. Please check your configuration and try again."
 	},
 	"orchestrator": {
-		"indexingFailedNoBlocks": "Indexing failed: No code blocks were successfully indexed. This usually indicates an embedder configuration issue.",
-		"indexingFailedCritical": "Indexing failed: No code blocks were successfully indexed despite finding files to process. This indicates a critical embedder failure.",
+		"indexingFailedNoBlocks": "Indexing failed: No code blocks were successfully indexed. This usually indicates an embedder configuration issue. Please check your API key, endpoint URL, and model settings.",
+		"indexingFailedCritical": "Indexing failed: No code blocks were successfully indexed despite finding files to process. This indicates a critical embedder failure. Please verify your embedder configuration and API connectivity.",
 		"fileWatcherStarted": "File watcher started.",
 		"fileWatcherStopped": "File watcher stopped.",
-		"failedDuringInitialScan": "Failed during initial scan: {{errorMessage}}",
+		"failedDuringInitialScan": "Failed during initial scan: {{errorMessage}}. Please check your configuration and try again.",
 		"unknownError": "Unknown error",
-		"indexingRequiresWorkspace": "Indexing requires an open workspace folder"
+		"indexingRequiresWorkspace": "Indexing requires an open workspace folder. Please open a folder or workspace to enable code indexing."
+	},
+	"openai": {
+		"invalidResponseFormat": "Invalid response format from OpenAI API. Please check your API key and model configuration."
 	}
 }

src/services/code-index/__tests__/manager.spec.ts

@@ -373,7 +373,7 @@ describe("CodeIndexManager - handleSettingsChange regression", () => {
 			expect(mockServiceFactoryInstance.validateEmbedder).toHaveBeenCalledWith(createdEmbedder)
 			expect(mockStateManager.setSystemState).toHaveBeenCalledWith(
 				"Error",
-				"embeddings:validation.authenticationFailed",
+				expect.stringContaining("embeddings:validation.authenticationFailed"),
 			)
 		})
 

src/services/code-index/__tests__/service-factory.spec.ts

@@ -795,7 +795,11 @@ describe("CodeIndexServiceFactory", () => {
 				},
 			}
 			mockConfigManager.getConfig.mockReturnValue(testConfig as any)
+
+			// Mock embedder with embedderInfo
+			mockEmbedderInstance.embedderInfo = { name: "openai" }
 			MockedOpenAiEmbedder.mockImplementation(() => mockEmbedderInstance)
+
 			const networkError = new Error("Network error")
 			mockEmbedderInstance.validateConfiguration.mockRejectedValue(networkError)
 
@@ -804,10 +808,12 @@ describe("CodeIndexServiceFactory", () => {
 			const result = await factory.validateEmbedder(embedder)
 
 			// Assert
-			expect(result).toEqual({
+			expect(result).toMatchObject({
 				valid: false,
-				error: "Network error",
+				// The error is wrapped in a translation key that includes the original error
+				error: expect.stringContaining("embeddingValidationFailed"),
 			})
+			// The result may also have a 'details' property, but we don't need to assert on it
 			expect(mockEmbedderInstance.validateConfiguration).toHaveBeenCalled()
 		})
 

src/services/code-index/embedders/openai-compatible.ts

@@ -348,8 +348,12 @@ export class OpenAICompatibleEmbedder implements IEmbedder {
 				// Log the error for debugging
 				console.error(`OpenAI Compatible embedder error (attempt ${attempts + 1}/${MAX_RETRIES}):`, error)
 
-				// Format and throw the error
-				throw formatEmbeddingError(error, MAX_RETRIES)
+				// Format and throw the error with context
+				throw formatEmbeddingError(error, MAX_RETRIES, {
+					provider: "OpenAI Compatible",
+					endpoint: this.baseUrl,
+					modelId: model,
+				})
 			}
 		}
 
@@ -360,46 +364,61 @@ export class OpenAICompatibleEmbedder implements IEmbedder {
 	 * Validates the OpenAI-compatible embedder configuration by testing endpoint connectivity and API key
 	 * @returns Promise resolving to validation result with success status and optional error message
 	 */
-	async validateConfiguration(): Promise<{ valid: boolean; error?: string }> {
-		return withValidationErrorHandling(async () => {
-			try {
-				// Test with a minimal embedding request
-				const testTexts = ["test"]
-				const modelToUse = this.defaultModelId
-
-				let response: OpenAIEmbeddingResponse
-
-				if (this.isFullUrl) {
-					// Test direct HTTP request for full endpoint URLs
-					response = await this.makeDirectEmbeddingRequest(this.baseUrl, testTexts, modelToUse)
-				} else {
-					// Test using OpenAI SDK for base URLs
-					response = (await this.embeddingsClient.embeddings.create({
-						input: testTexts,
-						model: modelToUse,
-						encoding_format: "base64",
-					})) as OpenAIEmbeddingResponse
-				}
+	async validateConfiguration(): Promise<{ valid: boolean; error?: string; details?: string }> {
+		return withValidationErrorHandling(
+			async () => {
+				try {
+					// Test with a minimal embedding request
+					const testTexts = ["test"]
+					const modelToUse = this.defaultModelId
+
+					let response: OpenAIEmbeddingResponse
+
+					if (this.isFullUrl) {
+						// Test direct HTTP request for full endpoint URLs
+						response = await this.makeDirectEmbeddingRequest(this.baseUrl, testTexts, modelToUse)
+					} else {
+						// Test using OpenAI SDK for base URLs
+						response = (await this.embeddingsClient.embeddings.create({
+							input: testTexts,
+							model: modelToUse,
+							encoding_format: "base64",
+						})) as OpenAIEmbeddingResponse
+					}
 
-				// Check if we got a valid response
-				if (!response?.data || response.data.length === 0) {
-					return {
-						valid: false,
-						error: "embeddings:validation.invalidResponse",
+					// Check if we got a valid response
+					if (!response?.data || response.data.length === 0) {
+						return {
+							valid: false,
+							error: t("embeddings:validation.invalidResponseFormat", {
+								provider: "OpenAI Compatible",
+							}),
+							details: t("embeddings:validation.checkEndpointCompatibility"),
+						}
 					}
-				}
 
-				return { valid: true }
-			} catch (error) {
-				// Capture telemetry for validation errors
-				TelemetryService.instance.captureEvent(TelemetryEventName.CODE_INDEX_ERROR, {
-					error: error instanceof Error ? error.message : String(error),
-					stack: error instanceof Error ? error.stack : undefined,
-					location: "OpenAICompatibleEmbedder:validateConfiguration",
-				})
-				throw error
-			}
-		}, "openai-compatible")
+					return { valid: true }
+				} catch (error) {
+					// Capture telemetry for validation errors
+					TelemetryService.instance.captureEvent(TelemetryEventName.CODE_INDEX_ERROR, {
+						error: error instanceof Error ? error.message : String(error),
+						stack: error instanceof Error ? error.stack : undefined,
+						location: "OpenAICompatibleEmbedder:validateConfiguration",
+						endpoint: this.baseUrl,
+						model: this.defaultModelId,
+					})
+					throw error
+				}
+			},
+			"openai-compatible",
+			undefined,
+			{
+				provider: "OpenAI Compatible",
+				endpoint: this.baseUrl,
+				modelId: this.defaultModelId,
+				apiKeySource: "OpenAI Compatible API Key setting",
+			},
+		)
 	}
 
 	/**

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

@@ -178,8 +178,11 @@ export class OpenAiEmbedder extends OpenAiNativeHandler implements IEmbedder {
 				// Log the error for debugging
 				console.error(`OpenAI embedder error (attempt ${attempts + 1}/${MAX_RETRIES}):`, error)
 
-				// Format and throw the error
-				throw formatEmbeddingError(error, MAX_RETRIES)
+				// Format and throw the error with context
+				throw formatEmbeddingError(error, MAX_RETRIES, {
+					provider: "OpenAI",
+					modelId: model,
+				})
 			}
 		}
 
@@ -190,34 +193,45 @@ export class OpenAiEmbedder extends OpenAiNativeHandler implements IEmbedder {
 	 * Validates the OpenAI embedder configuration by attempting a minimal embedding request
 	 * @returns Promise resolving to validation result with success status and optional error message
 	 */
-	async validateConfiguration(): Promise<{ valid: boolean; error?: string }> {
-		return withValidationErrorHandling(async () => {
-			try {
-				// Test with a minimal embedding request
-				const response = await this.embeddingsClient.embeddings.create({
-					input: ["test"],
-					model: this.defaultModelId,
-				})
-
-				// Check if we got a valid response
-				if (!response.data || response.data.length === 0) {
-					return {
-						valid: false,
-						error: t("embeddings:openai.invalidResponseFormat"),
+	async validateConfiguration(): Promise<{ valid: boolean; error?: string; details?: string }> {
+		return withValidationErrorHandling(
+			async () => {
+				try {
+					// Test with a minimal embedding request
+					const response = await this.embeddingsClient.embeddings.create({
+						input: ["test"],
+						model: this.defaultModelId,
+					})
+
+					// Check if we got a valid response
+					if (!response.data || response.data.length === 0) {
+						return {
+							valid: false,
+							error: t("embeddings:openai.invalidResponseFormat"),
+							details: t("embeddings:validation.checkEndpointCompatibility"),
+						}
 					}
-				}
 
-				return { valid: true }
-			} catch (error) {
-				// Capture telemetry for validation errors
-				TelemetryService.instance.captureEvent(TelemetryEventName.CODE_INDEX_ERROR, {
-					error: error instanceof Error ? error.message : String(error),
-					stack: error instanceof Error ? error.stack : undefined,
-					location: "OpenAiEmbedder:validateConfiguration",
-				})
-				throw error
-			}
-		}, "openai")
+					return { valid: true }
+				} catch (error) {
+					// Capture telemetry for validation errors
+					TelemetryService.instance.captureEvent(TelemetryEventName.CODE_INDEX_ERROR, {
+						error: error instanceof Error ? error.message : String(error),
+						stack: error instanceof Error ? error.stack : undefined,
+						location: "OpenAiEmbedder:validateConfiguration",
+						model: this.defaultModelId,
+					})
+					throw error
+				}
+			},
+			"openai",
+			undefined,
+			{
+				provider: "OpenAI",
+				modelId: this.defaultModelId,
+				apiKeySource: "OpenAI API Key setting",
+			},
+		)
 	}
 
 	get embedderInfo(): EmbedderInfo {

src/services/code-index/manager.ts

@@ -343,7 +343,30 @@ export class CodeIndexManager {
 		// Validate embedder configuration before proceeding
 		const validationResult = await this._serviceFactory.validateEmbedder(embedder)
 		if (!validationResult.valid) {
-			const errorMessage = validationResult.error || "Embedder configuration validation failed"
+			// Construct a detailed error message with context
+			const provider = this._configManager!.currentEmbedderProvider
+			const modelId = this._configManager!.currentModelId
+			let errorMessage =
+				validationResult.error ||
+				t("embeddings:serviceFactory.embeddingValidationFailed", {
+					provider,
+					error: "Unknown validation error",
+				})
+
+			// Add details if available
+			if ((validationResult as any).details) {
+				errorMessage += `. ${(validationResult as any).details}`
+			}
+
+			// Add helpful context based on the error
+			if (errorMessage.includes("401") || errorMessage.toLowerCase().includes("authentication")) {
+				errorMessage += `. Please check your API key in Settings > Code Index.`
+			} else if (errorMessage.includes("404") || errorMessage.toLowerCase().includes("not found")) {
+				errorMessage += `. Please verify the endpoint URL and model '${modelId}' are correct.`
+			} else if (errorMessage.includes("connection") || errorMessage.includes("ECONNREFUSED")) {
+				errorMessage += `. Please ensure the service is running and accessible.`
+			}
+
 			this._stateManager.setSystemState("Error", errorMessage)
 			throw new Error(errorMessage)
 		}