{"record":{"id":"4a36a5969c0cb6ae","repo":"spring-projects/spring-ai","slug":"failed-to-clear-the-index-for-session","errorCode":null,"errorMessage":"Failed to clear the index for session: ","messagePattern":"Failed to clear the index for session: ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"spring-ai-tool-search-tool/src/main/java/org/springframework/ai/tool/toolsearch/index/lucene/LuceneToolIndex.java","lineNumber":130,"sourceCode":"\t\treturn this.sessionIndexes.computeIfAbsent(sessionId, key -> {\n\t\t\ttry {\n\t\t\t\treturn new SessionIndex(this.analyzer);\n\t\t\t}\n\t\t\tcatch (IOException e) {\n\t\t\t\tthrow new RuntimeException(\"Failed to initialize Lucene index for session: \" + sessionId, e);\n\t\t\t}\n\t\t});\n\t}\n\n\t@Override\n\tpublic void clearIndex(String sessionId) {\n\t\tSessionIndex sessionIndex = this.sessionIndexes.remove(sessionId);\n\t\tif (sessionIndex != null) {\n\t\t\ttry {\n\t\t\t\tsessionIndex.close();\n\t\t\t}\n\t\t\tcatch (IOException e) {\n\t\t\t\tthrow new RuntimeException(\"Failed to clear the index for session: \" + sessionId, e);\n\t\t\t}\n\t\t}\n\t}\n\n\t@Override\n\tpublic void indexTool(String sessionId, ToolReference toolReference) {\n\t\tthis.add(sessionId, String.valueOf(this.counter.getAndIncrement()), toolReference.toolName(),\n\t\t\t\ttoolReference.summary());\n\t}\n\n\t@Override\n\tpublic void indexTools(String sessionId, List<ToolReference> toolReferences) {\n\t\tfor (ToolReference ref : toolReferences) {\n\t\t\tthis.add(sessionId, String.valueOf(this.counter.getAndIncrement()), ref.toolName(), ref.summary());\n\t\t}\n\t}\n\n\t@Override","sourceCodeStart":112,"sourceCodeEnd":148,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/spring-ai-tool-search-tool/src/main/java/org/springframework/ai/tool/toolsearch/index/lucene/LuceneToolIndex.java#L112-L148","documentation":"clearIndex(sessionId) removes and closes the SessionIndex for the given session. If closing the Lucene index writer/reader throws an IOException, it is wrapped in a RuntimeException naming the session. This indicates the index resources for that session could not be cleanly released.","triggerScenarios":"Calling clearIndex (or a delete/clear API that routes to it) while the underlying Lucene index is in a bad state — e.g. an already-closed writer, a pending merge failure, or an IO error flushing uncommitted changes during close.","commonSituations":"Concurrent clear while another thread is indexing, closing indexes after the backing directory was removed, or a crashed process left the index needing recovery on close.","solutions":["Inspect the wrapped IOException cause to see whether it is an AlreadyClosedException, LockObtainFailedException, or generic IO error.","Avoid calling clearIndex concurrently with indexTool/indexTools; synchronize or serialize clear and write operations per session.","If the session index is unrecoverable, drop the directory contents (or recreate the index instance) for that session.","Ensure the index directory still exists before clearing if an external process may have deleted it."],"exampleFix":"// before\ntoolIndex.indexTool(sessionId, ref);\ntoolIndex.clearIndex(sessionId); // concurrent clear race\n// after\nsynchronized (lock) {\n    toolIndex.indexTool(sessionId, ref);\n    toolIndex.clearIndex(sessionId);\n}","handlingStrategy":"try-catch","validationCode":"// Only clear when the session index exists and no writes are in flight\nif (indexHasSession(sessionId) && !isIndexing.get()) {\n    toolIndex.clearIndex(sessionId);\n}","typeGuard":null,"tryCatchPattern":"try {\n    toolIndex.clearIndex(sessionId);\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Failed to clear the index for session\")) {\n        logger.warn(\"Could not cleanly close index for {}: {}\", sessionId, e.getCause());\n        // treat session as cleared; rebuild index on next use\n    } else { throw e; }\n}","preventionTips":["Serialize clearIndex with indexTool/indexTools per session.","Call clearIndex before discarding a session to release Lucene resources deterministically.","Log and alert on close-time IOExceptions to catch filesystem degradation early."],"tags":["lucene","index","io","cleanup"],"backgroundTag":"file-close-failed","analyzedSha":"98a7beda4f29d80a71c5837eb4053b03a93a46f7","analyzedAt":"2026-09-11T14:15:49.441Z","contentChangedAt":"2026-09-11T14:15:49.441Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}