aeron-io/aeron · error · UncheckedIOException

<IOException message>

Error message

<IOException message>

What it means

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.

Solutions

1. Fix the filesystem hosting aeron.data.dir so it is mounted, healthy, and queryable (df/mount on the path).
2. Set aeron.driver.storage.check=false (AeronContext/DriverContext checkStorage=false) if the filesystem cannot support FileStore queries.
3. Point aeron.data.dir at a local disk-backed directory.
4. Inspect the wrapped IOException (ex.getCause()) for the root cause such as permission or I/O errors.

Example fix

// before
final MediaDriver mediaDriver = MediaDriver.launch(
    new MediaDriver.Context().dataDir("/mnt/nfs/aeron"));
// after
final MediaDriver mediaDriver = MediaDriver.launch(
    new MediaDriver.Context()
        .dataDir("/var/lib/aeron")
        .threadingMode(ThreadingMode.SHARED)); // local disk-backed data dir

import java.nio.file.*;
void verifyFileStoreQueryable(String dataDir) {
    try {
        Files.getFileStore(new java.io.File(dataDir).toPath());
    } catch (java.io.IOException e) {
        throw new IllegalStateException("cannot query file store for " + dataDir, e);
    }
}

boolean isUsableLocalDir(String dataDir) {
    try {
        return Files.getFileStore(new java.io.File(dataDir).toPath()) != null;
    } catch (java.io.IOException e) { return false; }
}

try {
    new FileStoreLogFactory(dataDir, filePageSize, true, threshold, errorHandler, counter);
} catch (java.io.UncheckedIOException e) {
    // fall back to local data dir or disable storage checks
    log.error("FileStore query failed: " + e.getCause());
}

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• <IOException message>
• clashing open clusterSessionId=
• className is empty
• ClusterMarkFile headerLength=
• ControlSession.RESPONSE_NOT_CONNECTED_MSG + ": " + session

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/a291215e5469872f. Report an issue: GitHub.

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/buffer/FileStoreLogFactory.java:88

        this.checkStorage = checkStorage;
        this.errorHandler = errorHandler;
        this.mappedBytesCounter = mappedBytesCounter;

        final File dataDir = new File(dataDirectoryName);

        publicationsDir = new File(dataDir, PUBLICATIONS);
        imagesDir = new File(dataDir, IMAGES);

        IoUtil.ensureDirectoryExists(publicationsDir, PUBLICATIONS);
        IoUtil.ensureDirectoryExists(imagesDir, IMAGES);

        try
        {
            fileStore = checkStorage ? Files.getFileStore(dataDir.toPath()) : null;
        }
        catch (final IOException ex)
        {
            throw new UncheckedIOException(ex);
        }
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public void close()
    {
    }

    /**
     * Create new {@link RawLog} in the publications' directory for the supplied triplet.
     *
     * @param correlationId    to use to distinguish this publication
     * @param termBufferLength length of each term
     * @param useSparseFiles   for the log buffer.
     * @return the newly allocated {@link RawLog}

View on GitHub (pinned to 6d60124e15)