Implements lazy (on-demand) creation of Qdrant collections.

Key points:

Defer collection creation until first write
Avoid allocating resources for unused branches
Improve error handling on collection access
Add promise-based locking to prevent race conditions
Optimize vector dimension validation
Reduce memory overhead through demand-driven initialization
Suggested commit title: feat(qdrant): add lazy collection initialization with concurrency safety

Optional extended description: Introduces on-demand collection creation in Qdrant. Collections are created only upon first write, preventing unnecessary allocation for inactive branches. Adds a promise-based lock to avoid concurrent creation races, improves error reporting when accessing missing collections, and streamlines vector dimension validation. This reduces memory usage and improves runtime efficiency.

 Smart re-indexing: only do full scan if collection doesn't exist or is empty

Author: yavpungggi

src/services/code-index/manager.ts

@@ -163,7 +163,6 @@ export class CodeIndexManager {
 		// Re-check Git branch watcher after services were recreated
 		await this._setupGitHeadWatcher()
 
-
 		// 5. Handle Indexing Start/Restart
 		// The enhanced vectorStore.initialize() in startIndexing() now handles dimension changes automatically
 		// by detecting incompatible collections and recreating them, so we rely on that for dimension changes
@@ -430,14 +429,24 @@ export class CodeIndexManager {
 				if (newBranch === this._lastKnownBranch) return
 				this._lastKnownBranch = newBranch
 				await this._recreateServices()
-				this._orchestrator?.startIndexing()
+
+				// Smart re-indexing: only do full scan if collection doesn't exist or is empty
+				// If collection exists with data, file watcher will handle incremental updates
+				const collectionExists = await this._serviceFactory?.getVectorStore()?.collectionExists()
+				if (!collectionExists) {
+					// New branch or first time indexing this branch - do full scan
+					this._orchestrator?.startIndexing()
+				} else {
+					// Collection exists - just validate/initialize without full scan
+					// File watcher will detect any file changes from the branch switch
+					await this._serviceFactory?.getVectorStore()?.initialize()
+				}
 			} catch (error) {
 				console.error("Failed to handle Git branch change:", error)
 			}
 		}, 250)
 	}
 
-
 	/**
 	 * Handle code index settings changes.
 	 * This method should be called when code index settings are updated
@@ -486,7 +495,6 @@ export class CodeIndexManager {
 					throw error
 				}
 			}
-
 		}
 	}
 }

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

@@ -19,6 +19,10 @@ export class QdrantVectorStore implements IVectorStore {
 	private readonly qdrantUrl: string = "http://localhost:6333"
 	private readonly workspacePath: string
 
+	// Lazy collection creation flag
+	private _collectionEnsured = false
+	private _ensurePromise?: Promise<void>
+
 	/**
 	 * Creates a new Qdrant vector store
 	 * @param workspacePath Path to the workspace
@@ -166,69 +170,110 @@ export class QdrantVectorStore implements IVectorStore {
 		try {
 			const collectionInfo = await this.client.getCollection(this.collectionName)
 			return collectionInfo
-		} catch (error: unknown) {
-			if (error instanceof Error) {
-				console.warn(
-					`[QdrantVectorStore] Warning during getCollectionInfo for "${this.collectionName}". Collection may not exist or another error occurred:`,
-					error.message,
-				)
+		} catch (error: any) {
+			// Check if this is a "not found" error (404) vs a connection error
+			const status = error?.status || error?.response?.status || error?.statusCode
+
+			if (status === 404) {
+				// Collection doesn't exist - this is expected, return null
+				return null
 			}
-			return null
+
+			// For other errors (connection issues, server errors, etc.), log and re-throw
+			const errorMessage = error?.message || String(error)
+			console.error(`[QdrantVectorStore] Error accessing collection "${this.collectionName}":`, errorMessage, {
+				status,
+			})
+
+			// Re-throw connection/server errors instead of silently returning null
+			throw new Error(`Failed to access Qdrant collection "${this.collectionName}": ${errorMessage}`)
 		}
 	}
 
 	/**
-	 * Initializes the vector store
+	 * Helper method to create or validate collection with proper dimension checking.
+	 * Extracted to eliminate code duplication between initialize() and _ensureCollectionExists().
 	 * @returns Promise resolving to boolean indicating if a new collection was created
 	 */
-	async initialize(): Promise<boolean> {
+	private async _createOrValidateCollection(): Promise<boolean> {
 		let created = false
-		try {
-			const collectionInfo = await this.getCollectionInfo()
+		const collectionInfo = await this.getCollectionInfo()
 
-			if (collectionInfo === null) {
-				// Collection info not retrieved (assume not found or inaccessible), create it
-				await this.client.createCollection(this.collectionName, {
-					vectors: {
-						size: this.vectorSize,
-						distance: this.DISTANCE_METRIC,
-						on_disk: true,
-					},
-					hnsw_config: {
-						m: 64,
-						ef_construct: 512,
-						on_disk: true,
-					},
-				})
-				created = true
+		if (collectionInfo === null) {
+			// Collection doesn't exist, create it
+			console.log(`[QdrantVectorStore] Creating new collection "${this.collectionName}"...`)
+			await this.client.createCollection(this.collectionName, {
+				vectors: {
+					size: this.vectorSize,
+					distance: this.DISTANCE_METRIC,
+					on_disk: true,
+				},
+				hnsw_config: {
+					m: 64,
+					ef_construct: 512,
+					on_disk: true,
+				},
+			})
+			await this._createPayloadIndexes()
+			console.log(`[QdrantVectorStore] Successfully created collection "${this.collectionName}"`)
+			created = true
+		} else {
+			// Collection exists, validate vector size
+			console.log(`[QdrantVectorStore] Collection "${this.collectionName}" already exists, validating...`)
+			const vectorsConfig = collectionInfo.config?.params?.vectors
+			let existingVectorSize: number
+
+			if (typeof vectorsConfig === "number") {
+				existingVectorSize = vectorsConfig
+			} else if (
+				vectorsConfig &&
+				typeof vectorsConfig === "object" &&
+				"size" in vectorsConfig &&
+				typeof vectorsConfig.size === "number"
+			) {
+				existingVectorSize = vectorsConfig.size
 			} else {
-				// Collection exists, check vector size
-				const vectorsConfig = collectionInfo.config?.params?.vectors
-				let existingVectorSize: number
-
-				if (typeof vectorsConfig === "number") {
-					existingVectorSize = vectorsConfig
-				} else if (
-					vectorsConfig &&
-					typeof vectorsConfig === "object" &&
-					"size" in vectorsConfig &&
-					typeof vectorsConfig.size === "number"
-				) {
-					existingVectorSize = vectorsConfig.size
-				} else {
-					existingVectorSize = 0 // Fallback for unknown configuration
-				}
+				existingVectorSize = 0
+			}
 
-				if (existingVectorSize === this.vectorSize) {
-					created = false // Exists and correct
-				} else {
-					// Exists but wrong vector size, recreate with enhanced error handling
-					created = await this._recreateCollectionWithNewDimension(existingVectorSize)
-				}
+			if (existingVectorSize !== this.vectorSize && existingVectorSize !== 0) {
+				// Dimension mismatch, recreate
+				console.warn(
+					`[QdrantVectorStore] Dimension mismatch for "${this.collectionName}": expected ${this.vectorSize}, found ${existingVectorSize}. Recreating...`,
+				)
+				created = await this._recreateCollectionWithNewDimension(existingVectorSize)
+				await this._createPayloadIndexes()
+			} else {
+				console.log(`[QdrantVectorStore] Collection "${this.collectionName}" validated successfully`)
 			}
+		}
+
+		return created
+	}
+
+	/**
+	 * Initializes the vector store by eagerly creating or validating the collection.
+	 *
+	 * This method is called by the orchestrator before full workspace scans to ensure
+	 * the collection exists upfront. For file-watcher-only workflows, collection creation
+	 * is deferred to _ensureCollectionExists() (lazy creation) on first write.
+	 *
+	 * When to use:
+	 * - initialize(): Called before full scans; creates collection eagerly
+	 * - _ensureCollectionExists(): Called on first write; creates collection lazily
+	 *
+	 * @returns Promise resolving to boolean indicating if a new collection was created
+	 * @throws {Error} If collection creation fails or Qdrant connection fails
+	 * @throws {Error} If vector dimension mismatch cannot be resolved
+	 */
+	async initialize(): Promise<boolean> {
+		try {
+			// Use shared helper to create or validate collection
+			const created = await this._createOrValidateCollection()
+
+			// Mark collection as ensured since we just created/validated it
+			this._collectionEnsured = true
 
-			// Create payload indexes
-			await this._createPayloadIndexes()
 			return created
 		} catch (error: any) {
 			const errorMessage = error?.message || error
@@ -349,6 +394,63 @@ export class QdrantVectorStore implements IVectorStore {
 		}
 	}
 
+	/**
+	 * Ensures the collection exists before writing.
+	 * Creates the collection and indexes lazily on first write.
+	 * Uses promise-based locking to prevent race conditions from concurrent calls.
+	 *
+	 * This method is called by upsertPoints() to implement lazy collection creation.
+	 * Unlike initialize(), which eagerly creates collections for full scans, this method
+	 * defers creation until the first write operation, reducing storage overhead for
+	 * branches that are never indexed.
+	 *
+	 * @throws {Error} If collection creation fails or Qdrant connection fails
+	 * @throws {Error} If vector dimension mismatch cannot be resolved
+	 */
+	private async _ensureCollectionExists(): Promise<void> {
+		if (this._collectionEnsured) return
+
+		// Prevent concurrent calls - return existing promise if already in progress
+		if (this._ensurePromise) {
+			return this._ensurePromise
+		}
+
+		// Create and store the ensure promise
+		this._ensurePromise = (async () => {
+			try {
+				// Use shared helper to create or validate collection
+				await this._createOrValidateCollection()
+
+				// Only set flag on success
+				this._collectionEnsured = true
+			} catch (error: any) {
+				// Reset promise on error so next call can retry
+				this._ensurePromise = undefined
+
+				const errorMessage = error?.message || error
+				console.error(
+					`[QdrantVectorStore] Failed to ensure collection "${this.collectionName}" exists:`,
+					errorMessage,
+				)
+
+				// If this is already a vector dimension mismatch error, re-throw as-is
+				if (error instanceof Error && error.cause !== undefined) {
+					throw error
+				}
+
+				// Otherwise, provide a user-friendly error message
+				throw new Error(
+					t("embeddings:vectorStore.qdrantConnectionFailed", { qdrantUrl: this.qdrantUrl, errorMessage }),
+				)
+			} finally {
+				// Clear promise after completion (success or failure)
+				this._ensurePromise = undefined
+			}
+		})()
+
+		return this._ensurePromise
+	}
+
 	/**
 	 * Upserts points into the vector store
 	 * @param points Array of points to upsert
@@ -361,6 +463,9 @@ export class QdrantVectorStore implements IVectorStore {
 		}>,
 	): Promise<void> {
 		try {
+			// Ensure collection exists before writing
+			await this._ensureCollectionExists()
+
 			const processedPoints = points.map((point) => {
 				if (point.payload?.filePath) {
 					const segments = point.payload.filePath.split(path.sep).filter(Boolean)
@@ -421,6 +526,12 @@ export class QdrantVectorStore implements IVectorStore {
 		maxResults?: number,
 	): Promise<VectorStoreSearchResult[]> {
 		try {
+			// If collection doesn't exist yet, return empty results
+			const collectionInfo = await this.getCollectionInfo()
+			if (collectionInfo === null) {
+				return []
+			}
+
 			let filter = undefined
 
 			if (directoryPrefix) {
@@ -563,6 +674,13 @@ export class QdrantVectorStore implements IVectorStore {
 	 */
 	async clearCollection(): Promise<void> {
 		try {
+			// Only clear if collection exists
+			const exists = await this.collectionExists()
+			if (!exists) {
+				console.warn(`[QdrantVectorStore] Skipping clear - collection "${this.collectionName}" does not exist`)
+				return
+			}
+
 			await this.client.delete(this.collectionName, {
 				filter: {
 					must: [],