{"record":{"id":"10ea04e0b9f4c7f3","repo":"alibaba/spring-ai-alibaba","slug":"failed-to-retrieve-item-from-file-system","errorCode":null,"errorMessage":"Failed to retrieve item from file system","messagePattern":"Failed to retrieve item from file system","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/store/stores/FileSystemStore.java","lineNumber":114,"sourceCode":"\t}\n\n\t@Override\n\tpublic Optional<StoreItem> getItem(List<String> namespace, String key) {\n\t\tvalidateGetItem(namespace, key);\n\n\t\tlock.readLock().lock();\n\t\ttry {\n\t\t\tPath itemPath = createItemPath(namespace, key);\n\t\t\tif (!Files.exists(itemPath)) {\n\t\t\t\treturn Optional.empty();\n\t\t\t}\n\n\t\t\tString itemJson = Files.readString(itemPath);\n\t\t\tStoreItem item = objectMapper.readValue(itemJson, StoreItem.class);\n\t\t\treturn Optional.of(item);\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tthrow new RuntimeException(\"Failed to retrieve item from file system\", e);\n\t\t}\n\t\tfinally {\n\t\t\tlock.readLock().unlock();\n\t\t}\n\t}\n\n\t@Override\n\tpublic boolean deleteItem(List<String> namespace, String key) {\n\t\tvalidateDeleteItem(namespace, key);\n\n\t\tlock.writeLock().lock();\n\t\ttry {\n\t\t\tPath itemPath = createItemPath(namespace, key);\n\t\t\tif (Files.exists(itemPath)) {\n\t\t\t\tFiles.delete(itemPath);\n\t\t\t\t// Clean up empty directories\n\t\t\t\tcleanupEmptyDirectories(itemPath.getParent());\n\t\t\t\treturn true;","sourceCodeStart":96,"sourceCodeEnd":132,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/store/stores/FileSystemStore.java#L96-L132","documentation":"FileSystemStore.getItem() reads the item file and deserializes it with Jackson, wrapping any exception in this RuntimeException under a read lock. It fires both when the file can't be read (missing/permission/IO) and when its JSON doesn't match StoreItem, even though 'item absent' is a normal condition.","triggerScenarios":"Calling getItem/profileItem/prefsItem for a key whose file doesn't exist (Files.readString throws NoSuchFileException), whose file has corrupt/hand-edited JSON, or with wrong file permissions.","commonSituations":"Looking up a never-stored item (expect Optional.empty but get this exception); files edited or truncated externally; library version upgrade changing StoreItem JSON shape; storage directory deleted while running.","solutions":["Check existence first or catch and treat NoSuchFileException as absent, since getItem may not return Optional.empty for missing files.","Inspect the chained cause: NoSuchFileException/AccessDeniedException vs JsonProcessingException to choose the fix.","Delete or repair corrupt JSON files in the store directory.","Migrate item files if a library upgrade changed the StoreItem format."],"exampleFix":"// before\nOptional<StoreItem> item = store.getItem(ns, key); // throws if absent\n// after\nOptional<StoreItem> item;\ntry {\n    item = store.getItem(ns, key);\n} catch (RuntimeException e) {\n    if (e.getCause() instanceof NoSuchFileException) {\n        item = Optional.empty();\n    } else {\n        throw e;\n    }\n}","handlingStrategy":"try-catch","validationCode":"java.nio.file.Path p = expectedItemPath(ns, key); // application-side path derivation\nif (!java.nio.file.Files.exists(p)) return Optional.empty();","typeGuard":null,"tryCatchPattern":"try { return store.getItem(ns, key); } catch (RuntimeException e) { if (e.getCause() instanceof java.nio.file.NoSuchFileException) return Optional.empty(); throw e; }","preventionTips":["Treat missing-file exceptions as absent items in a wrapper around getItem","Do not hand-edit or delete item JSON files while the app runs","Migrate item files after StoreItem format changes","Check directory permissions after redeployments"],"tags":["filesystem","json","deserialization","file-not-found"],"backgroundTag":"file-read-failed","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}