spring-projects/spring-ai · error · RuntimeException

Failed to initialize Lucene index for session:

Error message

Failed to initialize Lucene index for session: 

What it means

LuceneToolIndex creates a per-session Lucene index lazily via getOrCreateSessionIndex. If opening the in-memory/directory index (new SessionIndex) throws an IOException, it wraps it in a RuntimeException identifying the failing session. This usually indicates a filesystem/IO problem initializing the index store.

Source

Thrown at spring-ai-tool-search-tool/src/main/java/org/springframework/ai/tool/toolsearch/index/lucene/LuceneToolIndex.java:117

	}

	public LuceneToolIndex(float minScoreThreshold) {
		this.minScoreThreshold = minScoreThreshold;
		this.analyzer = new StandardAnalyzer();
	}

	/**
	 * Gets or creates a SessionIndex for the given sessionId.
	 * @param sessionId the session identifier
	 * @return the SessionIndex for the session
	 */
	private SessionIndex getOrCreateSessionIndex(String sessionId) {
		return this.sessionIndexes.computeIfAbsent(sessionId, key -> {
			try {
				return new SessionIndex(this.analyzer);
			}
			catch (IOException e) {
				throw new RuntimeException("Failed to initialize Lucene index for session: " + sessionId, e);
			}
		});
	}

	@Override
	public void clearIndex(String sessionId) {
		SessionIndex sessionIndex = this.sessionIndexes.remove(sessionId);
		if (sessionIndex != null) {
			try {
				sessionIndex.close();
			}
			catch (IOException e) {
				throw new RuntimeException("Failed to clear the index for session: " + sessionId, e);
			}
		}
	}

	@Override

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Check the wrapped IOException cause for the root IO error and fix it (permissions, disk space, path).
2. Verify the index directory configured for LuceneToolIndex exists and is writable by the running process.
3. Remove stale Lucene lock files (write.lock) from the index directory after a crash.
4. If the index is ephemeral, switch to an in-memory directory configuration to avoid filesystem issues.

Example fix

// before (read-only path in container)
LuceneToolIndex index = LuceneToolIndex.builder().directory(Path.of("/app/index")).build();
// after
LuceneToolIndex index = LuceneToolIndex.builder().directory(Path.of("/tmp/app-index")).build();

// Pre-flight directory check before creating the index
Path dir = Path.of(indexPath);
if (!Files.isDirectory(dir)) Files.createDirectories(dir);
if (!Files.isWritable(dir)) throw new IllegalStateException("Index directory not writable: " + dir);

try {
    searchClient.search(sessionId, query);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Failed to initialize Lucene index for session")) {
        logger.error("Index init failed for session {}: {}", sessionId, e.getCause(), e);
        // recreate index or fall back to non-indexed search
    } else { throw e; }
}

When it happens

Trigger: First tool search operation for a session ID when the underlying Lucene directory cannot be opened (e.g. disk full, no write permission to the configured index path, corrupted lock file).

Common situations: Running in containers with read-only filesystems, missing/invalid index directory configuration, stale Lucene write locks left by a crashed process, or permission problems under a restricted service account.

Related errors

• Failed to search index
• Failed to clear the index for session:
• Failed to add document to index
• Failed to commit changes to index for session:
• Failed to delete document from index

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/869f7282b791ed80. Report an issue: GitHub.