spring-projects/spring-ai · error · RuntimeException

Failed to delete document from index

Error message

Failed to delete document from index

What it means

Thrown by LuceneToolIndex.delete(sessionId, id) when IndexWriter.deleteDocuments(new Term(FIELD_ID, id)) throws an IOException. The delete is buffered in the writer until commit, so this error means Lucene could not even enqueue the delete (typically an I/O problem with the index directory or a closed writer), not that the document was absent.

Source

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

			.toolReferences(foundToolReferences)
			.totalMatches(foundToolReferences.size())
			.searchMetadata(SearchMetadata.builder().searchType(this.getClass().getSimpleName()).query(query).build())
			.build();
	}

	/**
	 * Deletes a tool from the index for the specified session by its ID.
	 * @param sessionId the session ID
	 * @param id the tool ID to delete
	 */
	public void delete(String sessionId, String id) {
		SessionIndex sessionIndex = this.sessionIndexes.get(sessionId);
		if (sessionIndex != null) {
			try {
				sessionIndex.writer.deleteDocuments(new Term(FIELD_ID, id));
			}
			catch (IOException e) {
				throw new RuntimeException("Failed to delete document from index", e);
			}
		}
	}

	/**
	 * 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) {

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Check the wrapped IOException cause to pinpoint the failing Lucene operation
2. Verify disk space and write permissions on the index directory, then retry delete()
3. If the writer was concurrently closed by clearIndex(), the documents are already gone — treat the operation as complete
4. If the index is corrupt, delete the session's index directory, re-add remaining tools, and commit
5. Serialize delete/clearIndex calls for the same session to avoid the documented race

Example fix

// before
index.delete(sessionId, toolId); // RuntimeException on IO failure
// after
try {
    index.delete(sessionId, toolId);
}
catch (RuntimeException e) {
    logger.error("failed to delete tool " + toolId + " from session " + sessionId, e);
    // check disk space; if session was concurrently cleared the tool is already removed
}

if (!index.hasSession(sessionId)) {
    return; // delete is a no-op: session index does not exist
}
File idxDir = new File(indexPath);
if (!Files.isWritable(idxDir.toPath())) {
    throw new IllegalStateException("Index directory not writable: " + indexPath);
}

try {
    index.delete(sessionId, toolId);
}
catch (RuntimeException e) {
    if (e.getCause() instanceof java.io.IOException ioEx) {
        logger.error("delete failed for tool " + toolId, ioEx);
        // if session was concurrently cleared the tool is already gone; otherwise check disk and retry
    }
}

When it happens

Trigger: Calling delete() for an existing session whose index directory is unwritable/full or whose files are corrupt; the session's writer was closed by a concurrent clearIndex() (write-after-close race); or the index directory was deleted externally before the delete operation.

Common situations: Disk-full while removing segments during merges; read-only filesystem after redeployment; concurrent clearIndex() closing the writer mid-delete; index directory on unstable network storage; a crashed process leaving a stale write lock so the reopened writer fails on I/O.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 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/d673e21de754a55e. Report an issue: GitHub.