aeron-io/aeron · error · IOException

unable to find 'cpuset.cpus.effective' in path '

Error message

unable to find 'cpuset.cpus.effective' in path '

What it means

CpusetV2Reader.retrieveEffectiveCgroupFilePath walks up the cgroup directory hierarchy looking for 'cpuset.cpus.effective'. If it reaches the cgroup root without finding the file, it throws an IOException. This indicates the process is running on a system without cgroup v2 cpuset data (or an unexpected mount layout), so the effective CPU set cannot be determined.

Solutions

  1. Verify cgroup v2 is enabled (mount -t cgroup2 /stat of /sys/fs/cgroup) and that cpuset.cpus.effective exists for the process's cgroup.
  2. If cgroup v1 is in use, use the v1 reader or disable cpuset-based topology checks in Aeron configuration.
  3. Run on a platform/kernel where cgroup v2 unified hierarchy is available, or skip the cpuset validation.
  4. Check that the cgroup root path Aeron detects matches the actual mount point of the container.
Defensive patterns

Strategy: fallback

Validate before calling

Path p = Path.of(cgroupRoot, "cpuset.cpus.effective");
boolean v2 = Files.exists(p); // guard before reading topology

Type guard

static boolean hasCgroupV2Cpuset(String cgroupRoot) { return Files.isRegularFile(Path.of(cgroupRoot, "cpuset.cpus.effective")); }

Try / catch

try {
    path = CpusetV2Reader.effectiveCgroupFilePath();
} catch (IOException e) {
    log.warn("no cgroup v2 cpuset file, skipping topology check: {}", e.getMessage());
}

Prevention

When it happens

Trigger: Calling CpusetV2Reader.effectiveCgroupFilePath (via retrieveEffectiveCgroupFilePath) on a filesystem where no directory from the process's cgroup path up to the cgroup root contains cpuset.cpus.effective — e.g. cgroup v1 systems or non-Linux platforms.

Common situations: Running on older Linux with cgroup v1 only, inside containers without the cpuset controller mounted, or on macOS/Windows where /sys/fs/cgroup does not exist.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/topology/CpusetV2Reader.java:75

        }
    }

    private Path retrieveEffectiveCgroupFilePath(final String pid) throws IOException
    {
        final String cgroupPath = resolveCgroupPath(pid);
        Path directory = cgroupRoot.resolve(cgroupPath.substring(1));

        while (true)
        {
            final Path candidate = directory.resolve(CPUSET_CPUS_EFFECTIVE);
            if (Files.exists(candidate))
            {
                return candidate;
            }

            if (directory.equals(cgroupRoot))
            {
                throw new IOException(
                    "unable to find '" + CPUSET_CPUS_EFFECTIVE + "' in path '" + cgroupRoot + "'");
            }

            directory = directory.getParent();
        }
    }

    private Cpuset readCpuSet(final String pid)
    {
        try
        {
            final Path effectiveCgroupFilePath = retrieveEffectiveCgroupFilePath(pid);
            final String formattedCpus = Files.readString(effectiveCgroupFilePath).strip();
            return new Cpuset(AffinityParser.parse(formattedCpus), formattedCpus);
        }
        catch (final IOException e)
        {
            throw new RuntimeException(e);

View on GitHub (pinned to 6d60124e15)