abhigyanpatwari/GitNexus · critical · RuntimeError

atomic overlay exchange is unavailable on this filesystem

Error message

atomic overlay exchange is unavailable on this filesystem

What it means

Thrown by `_exchange_at` when `renameat2` was found in libc but the actual syscall returned non-zero with errno `ENOSYS`, `EINVAL`, or `EOPNOTSUPP`. The kernel or the filesystem backing the directory does not support `RENAME_EXCHANGE`, so the atomic swap cannot be honored even though the platform looked capable.

Source

Thrown at eval/workflow_bench/promotion_apply.py:434

    except AttributeError as exc:
        raise RuntimeError("atomic overlay exchange is unavailable on this platform") from exc
    renameat2.argtypes = [ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint]
    renameat2.restype = ctypes.c_int
    if (
        renameat2(
            parent_descriptor,
            os.fsencode(left),
            parent_descriptor,
            os.fsencode(right),
            _RENAME_EXCHANGE,
        )
        == 0
    ):
        os.fsync(parent_descriptor)
        return
    error = ctypes.get_errno()
    if error in {errno.ENOSYS, errno.EINVAL, errno.EOPNOTSUPP}:
        raise RuntimeError("atomic overlay exchange is unavailable on this filesystem")
    raise OSError(error, os.strerror(error), f"{left} <-> {right}")


def _prepare_targets(
    payload: list[tuple[PurePosixPath, bytes]],
    repo_root: Path,
) -> tuple[Path, int, list[dict[str, Any]]]:
    """Resolve and snapshot every canonical/shipped destination exactly once."""

    root, root_descriptor = _open_repository_root(repo_root)
    prepared: list[dict[str, Any]] = []
    seen: set[PurePosixPath] = set()
    try:
        for relative, content in payload:
            for target in mirror_targets(relative):
                if target in seen:
                    raise ValueError(f"duplicate overlay destination: {target}")
                seen.add(target)

View on GitHub (pinned to d540b00184)

Solutions

  1. Move the repo_root onto a filesystem that supports RENAME_EXCHANGE — ext4, xfs, btrfs on a modern Linux kernel (>= 3.15).
  2. If in Docker, run the publish step with `--storage-driver=vfs` or write to a tmpfs/ext4 volume mounted into the container rather than the overlay root.
  3. Verify support directly: call `renameat2` on the exact target parent dir from a small Python probe and inspect errno; reproduce the exact directory + filesystem the bench uses.
  4. Avoid bind-mounting the repo over a network FS for the apply step; keep it on local disk.

Example fix

# before: repo_root lives on overlayfs (Docker default)
apply_promoted_overlay(overlay, repo_root=Path('/app/repo'))  # -> RuntimeError
# after: bind an ext4 volume
#   docker run -v /tmp/repo:/repo --tmpfs /tmp ...
apply_promoted_overlay(overlay, repo_root=Path('/repo'))
Defensive patterns

Strategy: validation

Validate before calling

import ctypes, errno, os, tempfile

def filesystem_supports_rename_exchange(directory: str) -> bool:
    """Probe RENAME_EXCHANGE on the exact FS that backs `directory`."""
    try:
        libc = ctypes.CDLL(None, use_errno=True)
        libc.renameat2.argtypes = [ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint]
        libc.renameat2.restype = ctypes.c_int
    except AttributeError:
        return False
    d = tempfile.mkdtemp(dir=directory)
    a = os.path.join(d, "a"); b = os.path.join(d, "b")
    open(a, "w").write("a"); open(b, "w").write("b")
    fd = os.open(d, os.O_RDONLY)
    rc = libc.renameat2(fd, b"a", fd, b"b", 2)  # RENAME_EXCHANGE
    err = ctypes.get_errno()
    os.close(fd); os.remove(a); os.remove(b); os.rmdir(d)
    if rc == 0:
        return True
    return err not in {errno.ENOSYS, errno.EINVAL, errno.EOPNOTSUPP}

Type guard

null

Try / catch

from workflow_bench.promotion_apply import apply_promoted_overlay

try:
    apply_promoted_overlay(overlay, expected_target_bases=bases)
except RuntimeError as exc:
    if "unavailable on this filesystem" in str(exc):
        # move repo_root to ext4/xfs/btrfs, or switch Docker storage driver
        ...
    raise

Prevention

When it happens

Trigger: Calling `apply_promoted_overlay` against a directory on overlayfs (common in Docker/OCI builds), network filesystems (NFS/CIFS/9p), certain FUSE filesystems, a kernel older than 3.15 that exposes the symbol but returns `ENOSYS`, or a filesystem that rejects `RENAME_EXCHANGE` with `EOPNOTSUPP`/`EINVAL`. The guard at promotion_apply.py:433 specifically classifies these three errnos as the filesystem-unsupported case.

Common situations: Builds inside Docker with overlay2 storage driver writing into a bind-mounted directory; Kubernetes pods on 9p or a virtualized FS; CI on a Linux kernel that lacks `CONFIG_RENAME_EXCHANGE`-equivalent support; exotic FUSE mounts. Different from error 400 — here the symbol exists but the call degrades.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@d540b00184 (2026-08-12). Data as JSON: /api/errors/7ceade571192fe25. Report an issue: GitHub.