spring-projects/spring-ai · error · RuntimeException

Failed to get index size for session:

Error message

Failed to get index size for session: 

What it means

Thrown by LuceneToolIndex.size(sessionId) when ensureAndGetReader() throws an IOException while reopening or accessing the session's IndexReader to report numDocs(). Unlike search or commit, this is only a read-only operation, so it almost always means the index directory or segment files are missing, unreadable, or corrupt. Note: an unknown sessionId returns 0 instead of throwing — only a known session whose reader cannot be opened raises this error.

Source

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

			}
		}
	}

	/**
	 * Returns the number of documents in the index for the specified session.
	 * @param sessionId the session ID
	 * @return document count, or 0 if session not found
	 */
	public int size(String sessionId) {
		SessionIndex sessionIndex = this.sessionIndexes.get(sessionId);
		if (sessionIndex == null) {
			return 0;
		}
		try {
			return sessionIndex.ensureAndGetReader().numDocs();
		}
		catch (IOException e) {
			throw new RuntimeException("Failed to get index size for session: " + sessionId, e);
		}
	}

	/**
	 * Returns the total number of documents across all session indexes.
	 * @return total document count
	 */
	public int totalSize() {
		int total = 0;
		for (String sessionId : this.sessionIndexes.keySet()) {
			total += size(sessionId);
		}
		return total;
	}

	@Override
	public void close() throws IOException {
		for (SessionIndex sessionIndex : this.sessionIndexes.values()) {

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Inspect the wrapped IOException cause to identify which session index file/operation failed
2. Verify the session's index directory exists and is readable by the process
3. If the index directory is gone or corrupt, re-initialize the session by re-adding its tools
4. Iterate sessions with try-catch around size(sessionId) in your own totalSize-like logic so one bad session does not break the aggregate
5. Check storage health (disk, NFS mounts, container volumes) backing the index directory

Example fix

// before
int count = index.totalSize(); // one unreadable session index fails the whole sweep
// after
int count = 0;
for (String sessionId : sessionIds) {
    try {
        count += index.size(sessionId);
    }
    catch (RuntimeException e) {
        logger.warn("size failed for session " + sessionId + ", counting as 0", e);
    }
}

File idxDir = new File(indexPath);
if (!idxDir.isDirectory() || !Files.isReadable(idxDir.toPath())) {
    throw new IllegalStateException("Session index directory missing/unreadable: " + indexPath);
}

try {
    int n = index.size(sessionId);
}
catch (RuntimeException e) {
    if (e.getCause() instanceof java.io.IOException) {
        logger.warn("cannot read index size for session " + sessionId + ", treating as 0", e);
    }
    // treat as 0 and trigger session re-initialization if needed
}

When it happens

Trigger: Calling size() (or totalSize(), which iterates size() for every session) after the index directory was deleted or made unreadable, the on-disk index is corrupt, or the reader reopen fails due to I/O errors on the storage backing the index.

Common situations: External cleanup job or deployment wiping the index directory while the app holds sessions; read-only remount in containers; corrupted segments after a crash mid-commit; totalSize() sweeping many sessions so one bad session index fails the whole count; network storage with stale NFS file handles.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Failed to initialize Lucene index for session:
• Failed to clear the index for session:
• Failed to add document to index
• Failed to commit changes to index for session:
• Failed to search index

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