unslothai/unsloth · critical · RuntimeError

Invalid path in the pinned {spec.name} source archive

Error message

Invalid path in the pinned {spec.name} source archive

What it means

Path-safety validation applied to every tar member: a member name is rejected if it is empty, absolute (leading /), contains a backslash, has any empty/./.. path component, has a Windows drive prefix on any component, or does not start with the expected single root directory (_archive_root_name(spec)). This blocks path-traversal (zip-slip) and cross-platform escape techniques during extraction.

Source

Thrown at studio/backend/utils/third_party_source.py:610

                    handle.write(chunk)
    except RuntimeError:
        raise
    except (OSError, urllib.error.URLError) as error:
        raise RuntimeError(f"Could not download the pinned {spec.name} source archive") from error


def _archive_member_parts(member: tarfile.TarInfo, spec: PinnedSource) -> tuple[str, ...]:
    name = member.name[:-1] if member.isdir() and member.name.endswith("/") else member.name
    parts = tuple(name.split("/"))
    if (
        not name
        or name.startswith("/")
        or "\\" in name
        or any(part in ("", ".", "..") for part in parts)
        or any(PureWindowsPath(part).drive for part in parts)
        or parts[0] != _archive_root_name(spec)
    ):
        raise RuntimeError(f"Invalid path in the pinned {spec.name} source archive")
    return parts


class _BoundedArchiveReader:
    def __init__(self, handle, limit: int):
        self._handle = handle
        self._limit = limit
        self._read = 0

    def read(self, size: int = -1) -> bytes:
        remaining = self._limit - self._read
        requested = remaining + 1 if size < 0 else min(size, remaining + 1)
        data = self._handle.read(requested)
        self._read += len(data)
        if self._read > self._limit:
            raise RuntimeError("The pinned source archive expands too large")
        return data

View on GitHub (pinned to 203007d190)

Solutions

1. Ensure archive_url is the canonical artifact for the pinned revision (GitHub codeload tar.gz preserves the expected root folder name)
2. Inspect the tarball: tar -tzf source.tar.gz | head — verify the top-level directory matches _archive_root_name(spec) and no entry is absolute or contains ../
3. Re-pack the archive locally with the correct single root directory and re-pin it (update source_tree_digest)
4. If the root name derivation is wrong for your host, fix the spec fields feeding _archive_root_name (repo/revision)

Example fix

# before: mirror tarball with different root
archive_url = "https://mirror.example.com/foo.tar.gz"  # root: foo/

# after: canonical codeload tarball with expected root 'foo-<sha>/'
archive_url = f"https://codeload.github.com/org/foo/tar.gz/{spec.revision}"

import tarfile
with tarfile.open("source.tar.gz") as tf:
    for m in tf:
        parts = m.name.strip("/").split("/")
        assert not m.name.startswith("/") and "\\" not in m.name
        assert all(p not in ("", ".", "..") for p in parts)
        assert parts[0] == expected_root, m.name

def archive_paths_safe(archive: Path, expected_root: str) -> bool:
    with tarfile.open(archive) as tf:
        for m in tf:
            name = m.name[:-1] if m.isdir() and m.name.endswith("/") else m.name
            parts = name.split("/")
            if (not name or name.startswith("/") or "\\" in name
                    or any(p in ("", ".", "..") for p in parts)
                    or parts[0] != expected_root):
                return False
    return True

try:
    ensure_pinned_source(spec)
except RuntimeError as e:
    if "Invalid path" in str(e):
        raise SystemExit("archive has unsafe/renamed root entries — repin to canonical tarball")

When it happens

Trigger: Streaming extraction (_install_archive_source) encounters a tar entry like `../../etc/passwd`, `/abs/path`, `C:\evil`, `pkg//file`, `.hidden/../x`, or an entry missing the expected `<repo>-<revision>/` root prefix (e.g. a repacked archive with a different top-level folder).

Common situations: Using a repacked/proxied tarball whose root directory was renamed (very common: GitHub codeload uses `<repo>-<full-sha>/` while mirrors may differ); a maliciously crafted archive in a supply-chain attack; archives produced by tools that emit `./`-prefixed entries.

Related errors

• The pinned {spec.name} archive contains duplicate files
• The pinned {spec.name} archive has too many entries
• The pinned {spec.name} archive contains a non-regular file
• dataset path may not contain null bytes
• dataset path may not contain '..' segments: {raw!r}

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/f0522cc0375f0511. Report an issue: GitHub.