{"record":{"id":"d54c40e588b6dbe7","repo":"alibaba/spring-ai-alibaba","slug":"failed-to-store-item-to-file-system","errorCode":null,"errorMessage":"Failed to store item to file system","messagePattern":"Failed to store item to 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":91,"sourceCode":"\t\tthis.objectMapper = new ObjectMapper();\n\t\tthis.objectMapper.findAndRegisterModules();\n\t\tinitializeRootDirectory();\n\t}\n\n\t@Override\n\tpublic void putItem(StoreItem item) {\n\t\tvalidatePutItem(item);\n\n\t\tlock.writeLock().lock();\n\t\ttry {\n\t\t\tPath itemPath = createItemPath(item.getNamespace(), item.getKey());\n\t\t\tensureDirectoryExists(itemPath.getParent());\n\n\t\t\tString itemJson = objectMapper.writeValueAsString(item);\n\t\t\tFiles.write(itemPath, itemJson.getBytes());\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tthrow new RuntimeException(\"Failed to store item to file system\", e);\n\t\t}\n\t\tfinally {\n\t\t\tlock.writeLock().unlock();\n\t\t}\n\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);","sourceCodeStart":73,"sourceCodeEnd":109,"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#L73-L109","documentation":"FileSystemStore.putItem() serializes the StoreItem to JSON and writes it to the item's file path under a write lock; any exception (Jackson serialization failure, IOException, missing parent directory) is wrapped in this RuntimeException. The write lock is released in finally.","triggerScenarios":"Calling putItem when the storage root is not writable, the filesystem is full, the path is invalid/too long, or the item cannot be JSON-serialized.","commonSituations":"Read-only mounted volume or container filesystem; permission denied on the store directory; disk quota exceeded; non-serializable value objects in the StoreItem.","solutions":["Check the chained cause to distinguish IOException (disk/permission) from Jackson serialization failure.","Verify the store root directory exists and the process has write permission.","Check free disk space and quota.","Ensure all values in the StoreItem are Jackson-serializable (no raw streams, non-POJOs)."],"exampleFix":"// before\nFiles.storeRoot = \"/var/data/store\"; // read-only mount\n// after\nFiles.storeRoot = \"/tmp/app-store\"; // writable location, or chmod the dir","handlingStrategy":"validation","validationCode":"java.nio.file.Path root = storeRoot;\nif (!java.nio.file.Files.isWritable(root)) {\n    throw new IllegalStateException(\"Store root not writable: \" + root);\n}\nif (root.toFile().getUsableSpace() < 10_000_000) {\n    throw new IllegalStateException(\"Low disk space for store: \" + root);\n}","typeGuard":null,"tryCatchPattern":"try { store.putItem(item); } catch (RuntimeException e) { log.error(\"put failed: {}\", e.getCause(), e); /* check perms/disk or serialization */ }","preventionTips":["Verify the store directory is writable at startup","Monitor disk space/quota on the store volume","Avoid read-only container mounts for the store path","Store only Jackson-serializable values in StoreItem"],"tags":["filesystem","io","json-serialization","store"],"backgroundTag":"file-write-failed","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}