{"record":{"id":"bcd4e7d5c56a9f2c","repo":"abhigyanpatwari/GitNexus","slug":"overlay-destination-must-already-be-a-regular-file","errorCode":null,"errorMessage":"overlay destination must already be a regular file: {target}","messagePattern":"overlay destination must already be a regular file: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"eval/workflow_bench/promotion_apply.py","lineNumber":113,"sourceCode":"    except BaseException:\n        # A partially written candidate/backup is never eligible for later\n        # cleanup through the replacements list, so remove it here before the\n        # staging exception escapes.\n        os.close(descriptor)\n        staged.unlink(missing_ok=True)\n        raise\n    else:\n        os.close(descriptor)\n    return staged\n\n\ndef _read_destination(path: Path, *, target: PurePosixPath) -> tuple[bytes, int]:\n    \"\"\"Read one mirror without following links and reject concurrent mutation.\"\"\"\n\n    try:\n        before = path.lstat()\n    except FileNotFoundError as exc:\n        raise ValueError(f\"overlay destination must already be a regular file: {target}\") from exc\n    if stat.S_ISLNK(before.st_mode) or not stat.S_ISREG(before.st_mode):\n        raise ValueError(f\"overlay destination must already be a regular file: {target}\")\n    descriptor = os.open(path, os.O_RDONLY | getattr(os, \"O_NOFOLLOW\", 0))\n    try:\n        opened = os.fstat(descriptor)\n        if not stat.S_ISREG(opened.st_mode):\n            raise ValueError(f\"overlay destination must already be a regular file: {target}\")\n        chunks: list[bytes] = []\n        while chunk := os.read(descriptor, 64 * 1024):\n            chunks.append(chunk)\n        after = os.fstat(descriptor)\n    finally:\n        os.close(descriptor)\n    try:\n        final = path.lstat()\n    except FileNotFoundError as exc:\n        raise ValueError(f\"overlay destination changed while being read: {target}\") from exc\n","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/eval/workflow_bench/promotion_apply.py#L95-L131","documentation":"_read_destination rejects a mirror that does not already exist as a regular file: the first branch catches FileNotFoundError on path.lstat() and chains it into a ValueError naming the target. The destination must be pre-created by a prior promotion; this read is for verification, not first-write.","triggerScenarios":"Calling _read_destination on a mirror path whose lstat raises FileNotFoundError — i.e. the promoted file was never written here, or was deleted before this read. Triggered when freeze_overlay/apply created some mirrors but not this one, or a sweep removed one.","commonSituations":"Partial promotion rollback left some mirrors missing; the MIRROR_SKILL_ROOTS list grew but the old snapshot predates a mirror; an external process (git clean, IDE) deleted one of the mirror files.","solutions":["Inspect the {target} path and confirm whether it should exist; if a mirror was added recently, re-run promotion from scratch.","Ensure no `git clean` / IDE file watcher removes mirror files between promotion and verification.","Re-run the full promotion pipeline so all mirrors are recreated atomically.","If the mirror list is intentionally stale, prune MIRROR_SKILL_ROOTS to match reality."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"from pathlib import Path\n\ndef ensure_all_mirrors_exist(mirrors: list[Path]) -> None:\n    missing = [str(p) for p in mirrors if not p.exists() or p.is_symlink()]\n    if missing:\n        raise SystemExit(f'mirrors missing or symlinked: {missing}; re-run full promotion')","typeGuard":null,"tryCatchPattern":"try:\n    data, mode = _read_destination(path, target=relative)\nexcept ValueError as exc:\n    if 'must already be a regular file' in str(exc) and 'No such file' in str(exc.__cause__):\n        log.error('mirror %s missing; rerun full promotion', relative)\n    raise","preventionTips":["Make promotion atomic — all mirrors created or none.","Stop `git clean` / IDE sweeps during promotion.","Keep MIRROR_SKILL_ROOTS pruned to mirrors that actually exist."],"tags":["overlay","promotion","mirror","filesystem","precondition"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}