{"record":{"id":"a291215e5469872f","repo":"aeron-io/aeron","slug":"ioexception-message","errorCode":null,"errorMessage":"<IOException message>","messagePattern":"<IOException message>","errorType":"exception","errorClass":"UncheckedIOException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/buffer/FileStoreLogFactory.java","lineNumber":88,"sourceCode":"        this.checkStorage = checkStorage;\n        this.errorHandler = errorHandler;\n        this.mappedBytesCounter = mappedBytesCounter;\n\n        final File dataDir = new File(dataDirectoryName);\n\n        publicationsDir = new File(dataDir, PUBLICATIONS);\n        imagesDir = new File(dataDir, IMAGES);\n\n        IoUtil.ensureDirectoryExists(publicationsDir, PUBLICATIONS);\n        IoUtil.ensureDirectoryExists(imagesDir, IMAGES);\n\n        try\n        {\n            fileStore = checkStorage ? Files.getFileStore(dataDir.toPath()) : null;\n        }\n        catch (final IOException ex)\n        {\n            throw new UncheckedIOException(ex);\n        }\n    }\n\n    /**\n     * {@inheritDoc}\n     */\n    @Override\n    public void close()\n    {\n    }\n\n    /**\n     * Create new {@link RawLog} in the publications' directory for the supplied triplet.\n     *\n     * @param correlationId    to use to distinguish this publication\n     * @param termBufferLength length of each term\n     * @param useSparseFiles   for the log buffer.\n     * @return the newly allocated {@link RawLog}","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/buffer/FileStoreLogFactory.java#L70-L106","documentation":"The Aeron driver's FileStoreLogFactory constructor queries the filesystem FileStore for the data directory via Files.getFileStore() to support storage-space checks. If this query throws an IOException, it is rethrown as an UncheckedIOException, failing construction of the log factory. This means the driver could not resolve which filesystem/device backs the aeron.data.dir.","triggerScenarios":"Creating a FileStoreLogFactory with checkStorage=true when Files.getFileStore(dataDir.toPath()) fails: the data directory path points at a location the OS cannot resolve a file store for (e.g. deleted/remounted mount, exotic FUSE filesystem, network mount rejection, or I/O error on the path).","commonSituations":"aeron.data.dir configured on a network filesystem (NFS/SMB) that getFileStore cannot query; the directory was on a mount that was unmounted after startup checks; running in containers with unusual overlay mounts; or disk I/O errors at driver startup.","solutions":["Fix the filesystem hosting aeron.data.dir so it is mounted, healthy, and queryable (df/mount on the path).","Set aeron.driver.storage.check=false (AeronContext/DriverContext checkStorage=false) if the filesystem cannot support FileStore queries.","Point aeron.data.dir at a local disk-backed directory.","Inspect the wrapped IOException (ex.getCause()) for the root cause such as permission or I/O errors."],"exampleFix":"// before\nfinal MediaDriver mediaDriver = MediaDriver.launch(\n    new MediaDriver.Context().dataDir(\"/mnt/nfs/aeron\"));\n// after\nfinal MediaDriver mediaDriver = MediaDriver.launch(\n    new MediaDriver.Context()\n        .dataDir(\"/var/lib/aeron\")\n        .threadingMode(ThreadingMode.SHARED)); // local disk-backed data dir","handlingStrategy":"try-catch","validationCode":"import java.nio.file.*;\nvoid verifyFileStoreQueryable(String dataDir) {\n    try {\n        Files.getFileStore(new java.io.File(dataDir).toPath());\n    } catch (java.io.IOException e) {\n        throw new IllegalStateException(\"cannot query file store for \" + dataDir, e);\n    }\n}","typeGuard":"boolean isUsableLocalDir(String dataDir) {\n    try {\n        return Files.getFileStore(new java.io.File(dataDir).toPath()) != null;\n    } catch (java.io.IOException e) { return false; }\n}","tryCatchPattern":"try {\n    new FileStoreLogFactory(dataDir, filePageSize, true, threshold, errorHandler, counter);\n} catch (java.io.UncheckedIOException e) {\n    // fall back to local data dir or disable storage checks\n    log.error(\"FileStore query failed: \" + e.getCause());\n}","preventionTips":["Place aeron.data.dir on a stable local disk-backed filesystem.","Confirm the data dir is mounted before driver startup (fs health check).","Run Files.getFileStore smoke-check in deployment scripts before launching the driver.","Keep the wrapped IOException cause when logging to expose the real root cause."],"tags":["java","filesystem","unchecked-ioexception","driver-startup"],"backgroundTag":"file-read-failed","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}