fix: handle Qdrant vector dimension mismatch when switching embedding models (#5562)

daniel-lxs · daniel-lxs · commit 41bce4b2b866 · 2025-07-10T09:50:56.000-05:00
- Added specific error handling for vector dimension mismatches
- Attempt to delete and recreate collection when dimensions change
- Provide clear, internationalized error message if recreation fails
- Added comprehensive test coverage for dimension mismatch scenarios
- Updated all locale files with new error message translations
diff --git a/src/i18n/locales/ca/embeddings.json b/src/i18n/locales/ca/embeddings.json
@@ -23,7 +23,8 @@
 		"failedToProcessBatchWithError": "No s'ha pogut processar el lot després de {{maxRetries}} intents: {{errorMessage}}"
 	},
 	"vectorStore": {
-		"qdrantConnectionFailed": "No s'ha pogut connectar a la base de dades vectorial Qdrant. Assegura't que Qdrant estigui funcionant i sigui accessible a {{qdrantUrl}}. Error: {{errorMessage}}"
+		"qdrantConnectionFailed": "No s'ha pogut connectar a la base de dades vectorial Qdrant. Assegura't que Qdrant estigui funcionant i sigui accessible a {{qdrantUrl}}. Error: {{errorMessage}}",
+		"vectorDimensionMismatch": "No s'ha pogut actualitzar l'índex de vectors per al nou model. Prova d'esborrar l'índex i tornar a començar. Detalls: {errorMessage}"
 	},
 	"validation": {
 		"authenticationFailed": "Ha fallat l'autenticació. Comproveu la vostra clau d'API a la configuració.",
diff --git a/src/i18n/locales/de/embeddings.json b/src/i18n/locales/de/embeddings.json
@@ -23,7 +23,8 @@
 		"failedToProcessBatchWithError": "Verarbeitung des Batches nach {{maxRetries}} Versuchen fehlgeschlagen: {{errorMessage}}"
 	},
 	"vectorStore": {
-		"qdrantConnectionFailed": "Verbindung zur Qdrant-Vektordatenbank fehlgeschlagen. Stelle sicher, dass Qdrant läuft und unter {{qdrantUrl}} erreichbar ist. Fehler: {{errorMessage}}"
+		"qdrantConnectionFailed": "Verbindung zur Qdrant-Vektordatenbank fehlgeschlagen. Stelle sicher, dass Qdrant läuft und unter {{qdrantUrl}} erreichbar ist. Fehler: {{errorMessage}}",
+		"vectorDimensionMismatch": "Aktualisierung des Vektorindex für neues Modell fehlgeschlagen. Bitte versuche, den Index zu löschen und von vorne zu beginnen. Details: {errorMessage}"
 	},
 	"validation": {
 		"authenticationFailed": "Authentifizierung fehlgeschlagen. Bitte überprüfe deinen API-Schlüssel in den Einstellungen.",
diff --git a/src/i18n/locales/en/embeddings.json b/src/i18n/locales/en/embeddings.json
@@ -23,7 +23,8 @@
 		"failedToProcessBatchWithError": "Failed to process batch after {{maxRetries}} attempts: {{errorMessage}}"
 	},
 	"vectorStore": {
-		"qdrantConnectionFailed": "Failed to connect to Qdrant vector database. Please ensure Qdrant is running and accessible at {{qdrantUrl}}. Error: {{errorMessage}}"
+		"qdrantConnectionFailed": "Failed to connect to Qdrant vector database. Please ensure Qdrant is running and accessible at {{qdrantUrl}}. Error: {{errorMessage}}",
+		"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.",
diff --git a/src/i18n/locales/es/embeddings.json b/src/i18n/locales/es/embeddings.json
@@ -23,7 +23,8 @@
 		"failedToProcessBatchWithError": "Error al procesar lote después de {{maxRetries}} intentos: {{errorMessage}}"
 	},
 	"vectorStore": {
-		"qdrantConnectionFailed": "Error al conectar con la base de datos vectorial Qdrant. Asegúrate de que Qdrant esté funcionando y sea accesible en {{qdrantUrl}}. Error: {{errorMessage}}"
+		"qdrantConnectionFailed": "Error al conectar con la base de datos vectorial Qdrant. Asegúrate de que Qdrant esté funcionando y sea accesible en {{qdrantUrl}}. Error: {{errorMessage}}",
+		"vectorDimensionMismatch": "No se pudo actualizar el índice de vectores para el nuevo modelo. Intenta borrar el índice y empezar de nuevo. Detalles: {errorMessage}"
 	},
 	"validation": {
 		"authenticationFailed": "Error de autenticación. Comprueba tu clave de API en los ajustes.",
diff --git a/src/i18n/locales/fr/embeddings.json b/src/i18n/locales/fr/embeddings.json
@@ -23,7 +23,8 @@
 		"failedToProcessBatchWithError": "Échec du traitement du lot après {{maxRetries}} tentatives : {{errorMessage}}"
 	},
 	"vectorStore": {
-		"qdrantConnectionFailed": "Échec de la connexion à la base de données vectorielle Qdrant. Veuillez vous assurer que Qdrant fonctionne et est accessible à {{qdrantUrl}}. Erreur : {{errorMessage}}"
+		"qdrantConnectionFailed": "Échec de la connexion à la base de données vectorielle Qdrant. Veuillez vous assurer que Qdrant fonctionne et est accessible à {{qdrantUrl}}. Erreur : {{errorMessage}}",
+		"vectorDimensionMismatch": "Échec de la mise à jour de l'index vectoriel pour le nouveau modèle. Veuillez essayer de vider l'index et de recommencer. Détails : {errorMessage}"
 	},
 	"validation": {
 		"authenticationFailed": "Échec de l'authentification. Veuillez vérifier votre clé API dans les paramètres.",
diff --git a/src/i18n/locales/hi/embeddings.json b/src/i18n/locales/hi/embeddings.json
@@ -23,7 +23,8 @@
 		"failedToProcessBatchWithError": "{{maxRetries}} प्रयासों के बाद बैच प्रसंस्करण विफल: {{errorMessage}}"
 	},
 	"vectorStore": {
-		"qdrantConnectionFailed": "Qdrant वेक्टर डेटाबेस से कनेक्ट करने में विफल। कृपया सुनिश्चित करें कि Qdrant चल रहा है और {{qdrantUrl}} पर पहुंच योग्य है। त्रुटि: {{errorMessage}}"
+		"qdrantConnectionFailed": "Qdrant वेक्टर डेटाबेस से कनेक्ट करने में विफल। कृपया सुनिश्चित करें कि Qdrant चल रहा है और {{qdrantUrl}} पर पहुंच योग्य है। त्रुटि: {{errorMessage}}",
+		"vectorDimensionMismatch": "नए मॉडल के लिए वेक्टर इंडेक्स को अपडेट करने में विफल। कृपया इंडेक्स को साफ़ करने और फिर से शुरू करने का प्रयास करें। विवरण: {errorMessage}"
 	},
 	"validation": {
 		"authenticationFailed": "प्रमाणीकरण विफल। कृपया सेटिंग्स में अपनी एपीआई कुंजी जांचें।",
diff --git a/src/i18n/locales/id/embeddings.json b/src/i18n/locales/id/embeddings.json
@@ -23,7 +23,8 @@
 		"failedToProcessBatchWithError": "Gagal memproses batch setelah {{maxRetries}} percobaan: {{errorMessage}}"
 	},
 	"vectorStore": {
-		"qdrantConnectionFailed": "Gagal terhubung ke database vektor Qdrant. Pastikan Qdrant berjalan dan dapat diakses di {{qdrantUrl}}. Error: {{errorMessage}}"
+		"qdrantConnectionFailed": "Gagal terhubung ke database vektor Qdrant. Pastikan Qdrant berjalan dan dapat diakses di {{qdrantUrl}}. Error: {{errorMessage}}",
+		"vectorDimensionMismatch": "Gagal memperbarui indeks vektor untuk model baru. Silakan coba bersihkan indeks dan mulai lagi. Detail: {errorMessage}"
 	},
 	"validation": {
 		"authenticationFailed": "Autentikasi gagal. Silakan periksa kunci API Anda di pengaturan.",
diff --git a/src/i18n/locales/it/embeddings.json b/src/i18n/locales/it/embeddings.json
@@ -23,7 +23,8 @@
 		"failedToProcessBatchWithError": "Elaborazione del batch fallita dopo {{maxRetries}} tentativi: {{errorMessage}}"
 	},
 	"vectorStore": {
-		"qdrantConnectionFailed": "Impossibile connettersi al database vettoriale Qdrant. Assicurati che Qdrant sia in esecuzione e accessibile su {{qdrantUrl}}. Errore: {{errorMessage}}"
+		"qdrantConnectionFailed": "Impossibile connettersi al database vettoriale Qdrant. Assicurati che Qdrant sia in esecuzione e accessibile su {{qdrantUrl}}. Errore: {{errorMessage}}",
+		"vectorDimensionMismatch": "Impossibile aggiornare l'indice vettoriale per il nuovo modello. Prova a cancellare l'indice e a ricominciare. Dettagli: {errorMessage}"
 	},
 	"validation": {
 		"authenticationFailed": "Autenticazione fallita. Controlla la tua chiave API nelle impostazioni.",
diff --git a/src/i18n/locales/ja/embeddings.json b/src/i18n/locales/ja/embeddings.json
@@ -23,7 +23,8 @@
 		"failedToProcessBatchWithError": "{{maxRetries}}回の試行後、バッチ処理に失敗しました：{{errorMessage}}"
 	},
 	"vectorStore": {
-		"qdrantConnectionFailed": "Qdrantベクターデータベースへの接続に失敗しました。Qdrantが実行中で{{qdrantUrl}}でアクセス可能であることを確認してください。エラー：{{errorMessage}}"
+		"qdrantConnectionFailed": "Qdrantベクターデータベースへの接続に失敗しました。Qdrantが実行中で{{qdrantUrl}}でアクセス可能であることを確認してください。エラー：{{errorMessage}}",
+		"vectorDimensionMismatch": "新しいモデルのベクトルインデックスの更新に失敗しました。インデックスをクリアして再試行してください。詳細：{errorMessage}"
 	},
 	"validation": {
 		"authenticationFailed": "認証に失敗しました。設定でAPIキーを確認してください。",
diff --git a/src/i18n/locales/ko/embeddings.json b/src/i18n/locales/ko/embeddings.json
@@ -23,7 +23,8 @@
 		"failedToProcessBatchWithError": "{{maxRetries}}번 시도 후 배치 처리 실패: {{errorMessage}}"
 	},
 	"vectorStore": {
-		"qdrantConnectionFailed": "Qdrant 벡터 데이터베이스에 연결하지 못했습니다. Qdrant가 실행 중이고 {{qdrantUrl}}에서 접근 가능한지 확인하세요. 오류: {{errorMessage}}"
+		"qdrantConnectionFailed": "Qdrant 벡터 데이터베이스에 연결하지 못했습니다. Qdrant가 실행 중이고 {{qdrantUrl}}에서 접근 가능한지 확인하세요. 오류: {{errorMessage}}",
+		"vectorDimensionMismatch": "새 모델의 벡터 인덱스를 업데이트하지 못했습니다. 인덱스를 지우고 다시 시작해 보세요. 세부 정보: {errorMessage}"
 	},
 	"validation": {
 		"authenticationFailed": "인증에 실패했습니다. 설정에서 API 키를 확인하세요.",
diff --git a/src/i18n/locales/nl/embeddings.json b/src/i18n/locales/nl/embeddings.json
@@ -23,7 +23,8 @@
 		"failedToProcessBatchWithError": "Verwerken van batch mislukt na {{maxRetries}} pogingen: {{errorMessage}}"
 	},
 	"vectorStore": {
-		"qdrantConnectionFailed": "Kan geen verbinding maken met Qdrant vectordatabase. Zorg ervoor dat Qdrant draait en toegankelijk is op {{qdrantUrl}}. Fout: {{errorMessage}}"
+		"qdrantConnectionFailed": "Kan geen verbinding maken met Qdrant vectordatabase. Zorg ervoor dat Qdrant draait en toegankelijk is op {{qdrantUrl}}. Fout: {{errorMessage}}",
+		"vectorDimensionMismatch": "Kan de vectorindex voor het nieuwe model niet bijwerken. Probeer de index te wissen en opnieuw te beginnen. Details: {errorMessage}"
 	},
 	"validation": {
 		"authenticationFailed": "Authenticatie mislukt. Controleer je API-sleutel in de instellingen.",
diff --git a/src/i18n/locales/pl/embeddings.json b/src/i18n/locales/pl/embeddings.json
@@ -23,7 +23,8 @@
 		"failedToProcessBatchWithError": "Nie udało się przetworzyć partii po {{maxRetries}} próbach: {{errorMessage}}"
 	},
 	"vectorStore": {
-		"qdrantConnectionFailed": "Nie udało się połączyć z bazą danych wektorowych Qdrant. Upewnij się, że Qdrant jest uruchomiony i dostępny pod adresem {{qdrantUrl}}. Błąd: {{errorMessage}}"
+		"qdrantConnectionFailed": "Nie udało się połączyć z bazą danych wektorowych Qdrant. Upewnij się, że Qdrant jest uruchomiony i dostępny pod adresem {{qdrantUrl}}. Błąd: {{errorMessage}}",
+		"vectorDimensionMismatch": "Nie udało się zaktualizować indeksu wektorowego dla nowego modelu. Spróbuj wyczyścić indeks i zacząć od nowa. Szczegóły: {errorMessage}"
 	},
 	"validation": {
 		"authenticationFailed": "Uwierzytelnianie nie powiodło się. Sprawdź swój klucz API w ustawieniach.",
diff --git a/src/i18n/locales/pt-BR/embeddings.json b/src/i18n/locales/pt-BR/embeddings.json
@@ -23,7 +23,8 @@
 		"failedToProcessBatchWithError": "Falha ao processar lote após {{maxRetries}} tentativas: {{errorMessage}}"
 	},
 	"vectorStore": {
-		"qdrantConnectionFailed": "Falha ao conectar com o banco de dados vetorial Qdrant. Certifique-se de que o Qdrant esteja rodando e acessível em {{qdrantUrl}}. Erro: {{errorMessage}}"
+		"qdrantConnectionFailed": "Falha ao conectar com o banco de dados vetorial Qdrant. Certifique-se de que o Qdrant esteja rodando e acessível em {{qdrantUrl}}. Erro: {{errorMessage}}",
+		"vectorDimensionMismatch": "Falha ao atualizar o índice de vetores para o novo modelo. Tente limpar o índice e começar novamente. Detalhes: {errorMessage}"
 	},
 	"validation": {
 		"authenticationFailed": "Falha na autenticação. Verifique sua chave de API nas configurações.",
diff --git a/src/i18n/locales/ru/embeddings.json b/src/i18n/locales/ru/embeddings.json
@@ -23,7 +23,8 @@
 		"failedToProcessBatchWithError": "Не удалось обработать пакет после {{maxRetries}} попыток: {{errorMessage}}"
 	},
 	"vectorStore": {
-		"qdrantConnectionFailed": "Не удалось подключиться к векторной базе данных Qdrant. Убедитесь, что Qdrant запущен и доступен по адресу {{qdrantUrl}}. Ошибка: {{errorMessage}}"
+		"qdrantConnectionFailed": "Не удалось подключиться к векторной базе данных Qdrant. Убедитесь, что Qdrant запущен и доступен по адресу {{qdrantUrl}}. Ошибка: {{errorMessage}}",
+		"vectorDimensionMismatch": "Не удалось обновить векторный индекс для новой модели. Попробуйте очистить индекс и начать сначала. Подробности: {errorMessage}"
 	},
 	"validation": {
 		"authenticationFailed": "Ошибка аутентификации. Проверьте свой ключ API в настройках.",
diff --git a/src/i18n/locales/tr/embeddings.json b/src/i18n/locales/tr/embeddings.json
@@ -23,7 +23,8 @@
 		"failedToProcessBatchWithError": "{{maxRetries}} denemeden sonra toplu işlem başarısız oldu: {{errorMessage}}"
 	},
 	"vectorStore": {
-		"qdrantConnectionFailed": "Qdrant vektör veritabanına bağlanılamadı. Qdrant'ın çalıştığından ve {{qdrantUrl}} adresinde erişilebilir olduğundan emin olun. Hata: {{errorMessage}}"
+		"qdrantConnectionFailed": "Qdrant vektör veritabanına bağlanılamadı. Qdrant'ın çalıştığından ve {{qdrantUrl}} adresinde erişilebilir olduğundan emin olun. Hata: {{errorMessage}}",
+		"vectorDimensionMismatch": "Yeni model için vektör dizini güncellenemedi. Lütfen dizini temizleyip yeniden başlatmayı deneyin. Detaylar: {errorMessage}"
 	},
 	"validation": {
 		"authenticationFailed": "Kimlik doğrulama başarısız oldu. Lütfen ayarlardan API anahtarınızı kontrol edin.",
diff --git a/src/i18n/locales/vi/embeddings.json b/src/i18n/locales/vi/embeddings.json
@@ -23,7 +23,8 @@
 		"failedToProcessBatchWithError": "Không thể xử lý lô sau {{maxRetries}} lần thử: {{errorMessage}}"
 	},
 	"vectorStore": {
-		"qdrantConnectionFailed": "Không thể kết nối với cơ sở dữ liệu vector Qdrant. Vui lòng đảm bảo Qdrant đang chạy và có thể truy cập tại {{qdrantUrl}}. Lỗi: {{errorMessage}}"
+		"qdrantConnectionFailed": "Không thể kết nối với cơ sở dữ liệu vector Qdrant. Vui lòng đảm bảo Qdrant đang chạy và có thể truy cập tại {{qdrantUrl}}. Lỗi: {{errorMessage}}",
+		"vectorDimensionMismatch": "Không thể cập nhật chỉ mục vector cho mô hình mới. Vui lòng thử xóa chỉ mục và bắt đầu lại. Chi tiết: {errorMessage}"
 	},
 	"validation": {
 		"authenticationFailed": "Xác thực không thành công. Vui lòng kiểm tra khóa API của bạn trong cài đặt.",
diff --git a/src/i18n/locales/zh-CN/embeddings.json b/src/i18n/locales/zh-CN/embeddings.json
@@ -23,7 +23,8 @@
 		"failedToProcessBatchWithError": "尝试 {{maxRetries}} 次后批次处理失败：{{errorMessage}}"
 	},
 	"vectorStore": {
-		"qdrantConnectionFailed": "连接 Qdrant 向量数据库失败。请确保 Qdrant 正在运行并可在 {{qdrantUrl}} 访问。错误：{{errorMessage}}"
+		"qdrantConnectionFailed": "连接 Qdrant 向量数据库失败。请确保 Qdrant 正在运行并可在 {{qdrantUrl}} 访问。错误：{{errorMessage}}",
+		"vectorDimensionMismatch": "无法更新新模型的向量索引。请尝试清除索引并重新开始。详细信息: {errorMessage}"
 	},
 	"validation": {
 		"authenticationFailed": "身份验证失败。请在设置中检查您的 API 密钥。",
diff --git a/src/i18n/locales/zh-TW/embeddings.json b/src/i18n/locales/zh-TW/embeddings.json
@@ -23,7 +23,8 @@
 		"failedToProcessBatchWithError": "嘗試 {{maxRetries}} 次後批次處理失敗：{{errorMessage}}"
 	},
 	"vectorStore": {
-		"qdrantConnectionFailed": "連接 Qdrant 向量資料庫失敗。請確保 Qdrant 正在執行並可在 {{qdrantUrl}} 存取。錯誤：{{errorMessage}}"
+		"qdrantConnectionFailed": "連接 Qdrant 向量資料庫失敗。請確保 Qdrant 正在執行並可在 {{qdrantUrl}} 存取。錯誤：{{errorMessage}}",
+		"vectorDimensionMismatch": "無法更新新模型的向量索引。請嘗試清除索引並重新開始。詳細資訊: {errorMessage}"
 	},
 	"validation": {
 		"authenticationFailed": "驗證失敗。請在設定中檢查您的 API 金鑰。",
diff --git a/src/services/code-index/vector-store/__tests__/qdrant-client.spec.ts b/src/services/code-index/vector-store/__tests__/qdrant-client.spec.ts
@@ -9,6 +9,9 @@ import { DEFAULT_MAX_SEARCH_RESULTS, DEFAULT_SEARCH_MIN_SCORE } from "../../cons
 vitest.mock("@qdrant/js-client-rest")
 vitest.mock("crypto")
 vitest.mock("../../../../utils/path")
+vitest.mock("../../../../i18n", () => ({
+	t: (key: string) => key, // Just return the key for testing
+}))
 vitest.mock("path", () => ({
 	...vitest.importActual("path"),
 	sep: "/",
@@ -674,7 +677,7 @@ describe("QdrantVectorStore", () => {
 			;(console.warn as any).mockRestore()
 		})
 
-		it("should re-throw error from deleteCollection when recreating collection with mismatched vectorSize", async () => {
+		it("should throw vectorDimensionMismatch error when deleteCollection fails during recreation", async () => {
 			const differentVectorSize = 768
 			mockQdrantClientInstance.getCollection.mockResolvedValue({
 				config: {
@@ -691,15 +694,65 @@ describe("QdrantVectorStore", () => {
 			vitest.spyOn(console, "error").mockImplementation(() => {})
 			vitest.spyOn(console, "warn").mockImplementation(() => {})
 
-			// The actual error message includes the URL and error details
-			await expect(vectorStore.initialize()).rejects.toThrow(
-				/Failed to connect to Qdrant vector database|vectorStore\.qdrantConnectionFailed/,
-			)
+			// The error message should contain our specific error about vector dimension mismatch
+			let caughtError: any
+			try {
+				await vectorStore.initialize()
+			} catch (error: any) {
+				caughtError = error
+			}
+
+			expect(caughtError).toBeDefined()
+			expect(caughtError.message).toContain("embeddings:vectorStore.vectorDimensionMismatch")
 
 			expect(mockQdrantClientInstance.getCollection).toHaveBeenCalledTimes(1)
 			expect(mockQdrantClientInstance.deleteCollection).toHaveBeenCalledTimes(1)
 			expect(mockQdrantClientInstance.createCollection).not.toHaveBeenCalled()
 			expect(mockQdrantClientInstance.createPayloadIndex).not.toHaveBeenCalled()
+			// Should log both the warning and the critical error
+			expect(console.warn).toHaveBeenCalledTimes(1)
+			expect(console.error).toHaveBeenCalledTimes(2) // One for the critical error, one for the outer catch
+			;(console.error as any).mockRestore()
+			;(console.warn as any).mockRestore()
+		})
+
+		it("should throw vectorDimensionMismatch error when createCollection fails during recreation", async () => {
+			const differentVectorSize = 768
+			mockQdrantClientInstance.getCollection.mockResolvedValue({
+				config: {
+					params: {
+						vectors: {
+							size: differentVectorSize,
+						},
+					},
+				},
+			} as any)
+
+			// Delete succeeds but create fails
+			mockQdrantClientInstance.deleteCollection.mockResolvedValue(true as any)
+			const createError = new Error("Create Collection Failed")
+			mockQdrantClientInstance.createCollection.mockRejectedValue(createError)
+			vitest.spyOn(console, "error").mockImplementation(() => {})
+			vitest.spyOn(console, "warn").mockImplementation(() => {})
+
+			// Should throw an error that contains our specific message
+			let caughtError: any
+			try {
+				await vectorStore.initialize()
+			} catch (error: any) {
+				caughtError = error
+			}
+
+			expect(caughtError).toBeDefined()
+			expect(caughtError.message).toContain("embeddings:vectorStore.vectorDimensionMismatch")
+
+			expect(mockQdrantClientInstance.getCollection).toHaveBeenCalledTimes(1)
+			expect(mockQdrantClientInstance.deleteCollection).toHaveBeenCalledTimes(1)
+			expect(mockQdrantClientInstance.createCollection).toHaveBeenCalledTimes(1)
+			expect(mockQdrantClientInstance.createPayloadIndex).not.toHaveBeenCalled()
+			// Should log warning, critical error, and outer error
+			expect(console.warn).toHaveBeenCalledTimes(1)
+			expect(console.error).toHaveBeenCalledTimes(2)
 			;(console.error as any).mockRestore()
 			;(console.warn as any).mockRestore()
 		})
diff --git a/src/services/code-index/vector-store/qdrant-client.ts b/src/services/code-index/vector-store/qdrant-client.ts
