abhigyanpatwari/GitNexus · critical · RuntimeError

atomic overlay exchange is unavailable on this platform

Error message

atomic overlay exchange is unavailable on this platform

What it means

Thrown by `_exchange_at` when `ctypes.CDLL(None).renameat2` is missing. The atomic overlay promoter relies on the Linux `renameat2(RENAME_EXCHANGE)` syscall to swap two directory entries in one operation; if the host libc has no `renameat2` symbol (non-Linux OS, or a glibc/kernel older than Linux 3.15), the swap primitive does not exist and the CAS overlay cannot run.

Source

Thrown at eval/workflow_bench/promotion_apply.py:417

def _same_entry(
    left: tuple[int, int, int, int, int, int],
    right: tuple[int, int, int, int, int, int],
) -> bool:
    return left[:2] == right[:2]


_RENAME_EXCHANGE = 2


def _exchange_at(parent_descriptor: int, left: str, right: str) -> None:
    """Atomically exchange two existing names in one held directory."""

    try:
        renameat2 = ctypes.CDLL(None, use_errno=True).renameat2
    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}")

View on GitHub (pinned to d540b00184)

Solutions

1. Run the promotion step inside a Linux >= 3.15 environment with a modern glibc (>= 2.28) — the typical fix is to switch the CI runner or dev container to a current Debian/Ubuntu/Fedora image.
2. Confirm the symbol is exported: `python3 -c "import ctypes; print(hasattr(ctypes.CDLL(None), 'renameat2'))"` — `False` confirms the platform is unsupported.
3. If you cannot get renameat2, avoid the atomic exchange path entirely: do not call `apply_promoted_overlay` / `committed_destination_base_digests` and use a non-atomic publish step instead.
4. For musl-based images (Alpine), switch to a glibc image or install gcompat so the dynamic loader exposes the glibc symbol.

Example fix

# before: running on macOS / unsupported libc
python -m workflow_bench.promotion_apply  # -> RuntimeError
# after: run on a Linux box with renameat2
python3 -c "import ctypes; assert hasattr(ctypes.CDLL(None), 'renameat2')"
python -m workflow_bench.promotion_apply

import ctypes

def supports_renameat2_exchange() -> bool:
    """True iff the host libc exposes renameat2 (necessary, not sufficient)."""
    try:
        return hasattr(ctypes.CDLL(None, use_errno=True), "renameat2")
    except OSError:
        return False

# call before any apply_promoted_overlay
if not supports_renameat2_exchange():
    raise SystemExit("promotion_apply needs a Linux >= 3.15 host with renameat2")

null

null

When it happens

Trigger: Calling `apply_promoted_overlay()` (or any path that stages and publishes overlay targets) on macOS, Windows, a BSD, a container running an ancient glibc, or any system where libc does not export the `renameat2` symbol. `ctypes.CDLL(None, use_errno=True).renameat2` raises `AttributeError` and is re-raised as this `RuntimeError`.

Common situations: Developer runs the workflow bench on a Mac or in CI on a non-Linux runner; a Linux box with glibc < 2.28 (renameat2 landed there); a statically linked or musl-based image without the symbol; running against an overlayfs-backed build root where the symbol probe still passes but the call fails (see error 401).

Related errors

• atomic overlay exchange parity check failed: {replacement['t
• atomic overlay exchange is unavailable on this filesystem
• Could not read ${GITNEXUS_RC_FILENAME}: ${(err as Error).mes
• Analyzer runtime payload directory is unavailable: ${absolut
• Analyzer runtime payload scan exceeded ${limits.runtimeEntri

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