abhigyanpatwari/GitNexus · error · SandboxError

task asset snapshot contains a special file: {path}

Error message

task asset snapshot contains a special file: {path}

What it means

Raised by _freeze_snapshot during the files walk when an entry reported by os.walk as a file is neither a symlink nor a regular file (stat.S_ISREG false). FIFOs, Unix sockets, character/block devices, and other special files are rejected because the snapshot model only supports regular files and (under dependencies/) symlinks.

Source

Thrown at eval/workflow_bench/task_assets.py:996

        "repo_identity": str(repo_identity),
        "resolved_sha": resolved_sha,
        "schema_version": 2,
    }
    return hashlib.sha256(json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()).hexdigest()


def _freeze_snapshot(root: Path) -> None:
    for current, directories, files in os.walk(root, topdown=False, followlinks=False):
        for name in files:
            path = Path(current) / name
            mode = path.lstat().st_mode
            relative = path.relative_to(root)
            if stat.S_ISLNK(mode):
                if not relative.parts or relative.parts[0] != "dependencies":
                    raise SandboxError(f"task asset snapshot contains an unexpected symlink: {path}")
                continue
            if not stat.S_ISREG(mode):
                raise SandboxError(f"task asset snapshot contains a special file: {path}")
            path.chmod(0o400 | (0o100 if stat.S_IMODE(mode) & 0o111 else 0))
        for name in directories:
            path = Path(current) / name
            mode = path.lstat().st_mode
            relative = path.relative_to(root)
            if stat.S_ISLNK(mode):
                if not relative.parts or relative.parts[0] != "dependencies":
                    raise SandboxError(f"task asset snapshot contains an unexpected symlink: {path}")
                continue
            if not stat.S_ISDIR(mode):
                raise SandboxError(f"task asset snapshot contains a special directory: {path}")
            path.chmod(0o500)
        Path(current).chmod(0o500)


def _thaw_tree(root: Path) -> None:
    for current, directories, files in os.walk(root, topdown=True, followlinks=False):
        Path(current).chmod(0o700)

View on GitHub (pinned to d540b00184)

Solutions

1. Delete the special file from the captured source tree before capture (rm the .sock / FIFO / device).
2. Exclude the directory containing the special file from the sandbox_copy declaration.
3. If the special file is legitimately needed, the snapshot format does not support it — generate it inside the clone at run time instead.

Example fix

# before: dev socket captured into the snapshot
repo/.vite/vite.sock  ->  freeze raises 'special file'

# after: exclude the runtime socket dir from sandbox_copy
sandbox_copy = ['src', 'public']   # do not capture '.vite' or '.cache'

import os, stat
from pathlib import Path

def assert_only_regular_files(root: Path) -> None:
    for current, _, files in os.walk(root, followlinks=False):
        for name in files:
            mode = (Path(current) / name).lstat().st_mode
            if not (stat.S_ISREG(mode) or stat.S_ISLNK(mode)):
                raise ValueError(f'non-regular file would be rejected by freeze: {Path(current)/name}')

# Run before cache.prepare; delete or exclude FIFOs/sockets/devices from the captured tree.

When it happens

Trigger: The captured snapshot tree contains a non-regular file: a leftover mkfifo FIFO, a .sock unix socket from a dev server, a /dev bind, or a door on Solaris. os.walk lists it under files but lstat says it is not S_ISREG.

Common situations: Pointing sandbox_copy at a repo dir that contains a dev-server socket or build FIFO; test fixtures that create named pipes; container bind-mounts leaking device nodes; CI cache directories with socket files.

Related errors

• {label} must be a real directory: {lexical}: {exc}
• {label} must be a real directory: {lexical}
• {label} must not traverse symlinks: {lexical}
• {label} must be a real non-symlink directory: {path}
• {label} contains an unsafe path component: {relative}

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