{"record":{"id":"869f7282b791ed80","repo":"spring-projects/spring-ai","slug":"failed-to-initialize-lucene-index-for-session","errorCode":null,"errorMessage":"Failed to initialize Lucene index for session: ","messagePattern":"Failed to initialize Lucene 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":117,"sourceCode":"\t}\n\n\tpublic LuceneToolIndex(float minScoreThreshold) {\n\t\tthis.minScoreThreshold = minScoreThreshold;\n\t\tthis.analyzer = new StandardAnalyzer();\n\t}\n\n\t/**\n\t * Gets or creates a SessionIndex for the given sessionId.\n\t * @param sessionId the session identifier\n\t * @return the SessionIndex for the session\n\t */\n\tprivate SessionIndex getOrCreateSessionIndex(String sessionId) {\n\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","sourceCodeStart":99,"sourceCodeEnd":135,"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#L99-L135","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Check the wrapped IOException cause for the root IO error and fix it (permissions, disk space, path).","Verify the index directory configured for LuceneToolIndex exists and is writable by the running process.","Remove stale Lucene lock files (write.lock) from the index directory after a crash.","If the index is ephemeral, switch to an in-memory directory configuration to avoid filesystem issues."],"exampleFix":"// before (read-only path in container)\nLuceneToolIndex index = LuceneToolIndex.builder().directory(Path.of(\"/app/index\")).build();\n// after\nLuceneToolIndex index = LuceneToolIndex.builder().directory(Path.of(\"/tmp/app-index\")).build();","handlingStrategy":"try-catch","validationCode":"// Pre-flight directory check before creating the index\nPath dir = Path.of(indexPath);\nif (!Files.isDirectory(dir)) Files.createDirectories(dir);\nif (!Files.isWritable(dir)) throw new IllegalStateException(\"Index directory not writable: \" + dir);","typeGuard":null,"tryCatchPattern":"try {\n    searchClient.search(sessionId, query);\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Failed to initialize Lucene index for session\")) {\n        logger.error(\"Index init failed for session {}: {}\", sessionId, e.getCause(), e);\n        // recreate index or fall back to non-indexed search\n    } else { throw e; }\n}","preventionTips":["Ensure the index directory is writable in every deployment (container, k8s securityContext).","Clean stale write.lock files after abnormal shutdown.","Monitor disk space where Lucene indexes live.","Prefer in-memory directories for ephemeral session indexes."],"tags":["lucene","index","io","search"],"backgroundTag":"module-init-failed","analyzedSha":"98a7beda4f29d80a71c5837eb4053b03a93a46f7","analyzedAt":"2026-09-11T14:15:49.441Z","contentChangedAt":"2026-09-11T14:15:49.441Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}