abhigyanpatwari/GitNexus · warning · FileExistsError

could not allocate a unique overlay staging file

Error message

could not allocate a unique overlay staging file

What it means

All errors below are raised by internal helpers of `eval/workflow_bench/promotion_apply.py` and propagate to the caller of the public entry points: `apply_promoted_overlay(overlay, repo_root, *, expected_digest, expected_target_bases)`, `destination_base_digests(overlay, repo_root)`, `committed_destination_base_digests(overlay, repo_root, *, ref)` and `freeze_overlay(overlay, destination)`. The module applies promoted skill overlays across the canonical skill tree plus its shipped mirrors (`gitnexus/skills`, `gitnexus-claude-plugin/skills`) in a TOCTOU-hardened, symlink-rejecting, descriptor-bound transaction. `_stage_replacement_at` loops up to 100 times, each generating a fresh `.wfevolve-<token_hex(16)>` name and opening with `O_CREAT | O_EXCL`. If every attempt raises `FileExistsError`, it gives up with this `FileExistsError`. With 128 bits of randomness a genuine collision is astronomically unlikely, so this almost always indicates a broken filesystem/RNG or a directory flooded with stale `.wfevolve-*` entries.

Source

Thrown at eval/workflow_bench/promotion_apply.py:370

            try:
                os.unlink(name, dir_fd=parent_descriptor)
                os.fsync(parent_descriptor)
            except OSError as cleanup_exc:
                raise _StagingCleanupError(name, exc, cleanup_exc) from exc
            raise
        else:
            os.close(descriptor)
            try:
                os.fsync(parent_descriptor)
            except OSError as exc:
                try:
                    os.unlink(name, dir_fd=parent_descriptor)
                    os.fsync(parent_descriptor)
                except OSError as cleanup_exc:
                    raise _StagingCleanupError(name, exc, cleanup_exc) from exc
                raise
            return name
    raise FileExistsError("could not allocate a unique overlay staging file")


def _temporary_exists(parent_descriptor: int, name: str) -> bool:
    try:
        os.stat(name, dir_fd=parent_descriptor, follow_symlinks=False)
    except FileNotFoundError:
        return False
    return True


def _unlink_temporary(parent_descriptor: int, name: str) -> None:
    try:
        os.unlink(name, dir_fd=parent_descriptor)
    except FileNotFoundError:
        return
    os.fsync(parent_descriptor)

View on GitHub (pinned to d540b00184)

Solutions

1. Remove stale staging files: delete unreferenced `.wfevolve-*` entries from the mirror directories.
2. Verify the Python RNG works: `len({secrets.token_hex(16) for _ in range(100)}) == 100`.
3. If the filesystem has broken `O_EXCL`, move the checkout to a POSIX-correct local filesystem and retry.

Example fix

// before
apply_promoted_overlay(overlay, repo_root=root)
// after
import glob
for stale in glob.glob(str(root / '**' / '.wfevolve-*'), recursive=True):
    os.unlink(stale)
apply_promoted_overlay(overlay, repo_root=root)

import glob
stale = glob.glob(str(root / '**' / '.wfevolve-*'), recursive=True)
if stale:
    for s in stale: os.unlink(s)
# also sanity-check the RNG
assert len({secrets.token_hex(16) for _ in range(100)}) == 100

except FileExistsError as exc:
    if 'could not allocate a unique overlay staging file' in str(exc):
        log.warning('staging name collision; clearing stale .wfevolve-* and retrying once')
        clear_stale_wfevolve(root)
        apply_promoted_overlay(overlay, repo_root=root)

When it happens

Trigger: 100 consecutive `O_EXCL` create attempts all collided with an existing entry — either the directory already contains huge numbers of `.wfevolve-*` files, the RNG is degenerate, or the filesystem mis-reports existence.

Common situations: Prior crashed promotions left thousands of stale staging files in a mirror dir; `secrets.token_hex` entropy source unavailable in a locked-down container; a filesystem (some FUSE/network mounts) with broken exclusive-create semantics.

Related errors

• short write while staging overlay replacement
• candidate destination parent must be a real directory: {rela
• candidate destination is unreadable: {relative}: {exc}
• candidate destination must be a regular non-symlink file: {r
• short write while staging candidate overlay

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