aeron-io/aeron · error · RuntimeException

failed to read link file=

Error message

failed to read link file=${linkFile}

What it means

ClusterToolOperator reads a link file (a small ASCII file pointing at the mark file directory) with Files.readAllBytes; any IOException is rethrown as RuntimeException("failed to read link file=..."). This happens when discovering a cluster's mark file directory via its link file and the file cannot be read.

Solutions

1. Check the link file exists at the given path and is readable by the tool's user (ls -l, chmod).
2. Verify you are pointing the tool at the correct cluster directory.
3. Ensure the link file contains a valid ASCII path to the mark file directory and is not empty or corrupted.
4. Fix filesystem/mount issues (e.g. stale NFS mount) that cause IOException during read.

Example fix

// before
File linkFile = new File(clusterDir, "link-file"); // may not exist
operator.usage(clusterDir, ...);
// after
File linkFile = new File(clusterDir, "link-file");
if (!linkFile.isFile() || !linkFile.canRead())
{
    throw new IllegalStateException("cannot read link file=" + linkFile);
}

File linkFile = new File(clusterDir, "link-file");
if (!linkFile.isFile() || !linkFile.canRead())
{
    throw new IllegalStateException("link file missing/unreadable: " + linkFile);
}

try
{
    operator.usage(clusterDir, ...);
}
catch (RuntimeException ex)
{
    if (ex.getMessage() != null && ex.getMessage().startsWith("failed to read link file"))
    {
        // check path/permissions
    }
    else throw ex;
}

When it happens

Trigger: Constructing/using ClusterToolOperator against a cluster directory containing a link file that cannot be read: file missing, unreadable permissions, path is a directory, or I/O error during readAllBytes.

Common situations: Pointing ClusterTool at the wrong directory where the link file is absent; running as a user without read permission; cluster dir mounted but the link file truncated or removed by cleanup jobs.

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

• failed to read link file=" + linkFile
• UncheckedIOException while backing up recording log
• failed to write recording
• UncheckedIOException while updating recording log
• [clientId= , clientName= ] Failed to map log buffer with…

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/ClusterToolOperator.java:1327

    File resolveClusterMarkFileDir(final File dir)
    {
        final File linkFile = new File(dir, ClusterMarkFile.LINK_FILENAME);
        return linkFile.exists() ? resolveDirectoryFromLinkFile(linkFile) : dir;
    }

    File resolveDirectoryFromLinkFile(final File linkFile)
    {
        final File markFileDir;

        try
        {
            final byte[] bytes = Files.readAllBytes(linkFile.toPath());
            final String markFileDirPath = new String(bytes, US_ASCII).trim();
            markFileDir = new File(markFileDirPath);
        }
        catch (final IOException ex)
        {
            throw new RuntimeException("failed to read link file=" + linkFile, ex);
        }

        return markFileDir;
    }

    /**
     * Channel to use.
     *
     * @return channel to use.
     */
    protected String toolChannel()
    {
        return toolChannel;
    }

    /**
     * Stream id to use.
     *

View on GitHub (pinned to 6d60124e15)