666ghj/MiroFish · error · StarHistoryError

could not read {label}

Error message

could not read {label}

What it means

_read_limited maps any non-ENOENT OSError while opening/reading the file to 'could not read {label}' ('could not read history state'). __cause__ preserves the original errno for diagnosis.

Source

Thrown at scripts/star_history.py:504

                raise StarHistoryError("output directory cannot be a symbolic link")
        if target.is_symlink():
            raise StarHistoryError("output file cannot be a symbolic link")
    try:
        resolved_parent = target.parent.resolve(strict=False)
        resolved_parent.relative_to(root)
    except (OSError, ValueError) as exc:
        raise StarHistoryError("output path escaped the workspace") from exc
    return resolved_parent / target.name


def _read_limited(path: Path, limit: int, label: str) -> bytes:
    try:
        with path.open("rb") as handle:
            payload = handle.read(limit + 1)
    except FileNotFoundError as exc:
        raise StarHistoryError(f"{label} is missing") from exc
    except OSError as exc:
        raise StarHistoryError(f"could not read {label}") from exc
    if len(payload) > limit:
        raise StarHistoryError(f"{label} exceeded the size limit")
    return payload


def load_star_count_file(path: Path) -> int:
    """Read a tiny, symlink-safe decimal count produced by the fetch-only step."""

    flags = os.O_RDONLY
    if hasattr(os, "O_NOFOLLOW"):
        flags |= os.O_NOFOLLOW
    try:
        descriptor = os.open(path, flags)
    except OSError as exc:
        raise StarHistoryError("Star count file is missing or unsafe") from exc
    try:
        metadata = os.fstat(descriptor)
        if not stat.S_ISREG(metadata.st_mode):

View on GitHub (pinned to b5b53acc57)

Solutions

1. Inspect exc.__cause__ (errno) from the caught StarHistoryError
2. chmod/chown the state file so the invoking user can read it
3. If on NFS/network storage, retry or move the workspace local
4. Check fd limits (ulimit -n) if EMFILE

Example fix

# before: written by root in a container step
sudo python scripts/star_history.py ...
# after
python scripts/star_history.py ...  # same user reads and writes

import os
p = ws / '.github/star-history/history.json'
if p.exists() and not os.access(p, os.R_OK):
    raise PermissionError(f'no read access: {p}')

except StarHistoryError as e:
    if str(e) == "could not read history state" and e.__cause__:
        handle_errno(e.__cause__.errno)  # EACCES -> chmod, EIO -> retry
    raise

When it happens

Trigger: Opening .github/star-history/history.json fails with EACCES (no read permission), EISDIR, EMFILE (fd exhaustion), or a read() interrupted by an I/O error (bad disk, NFS stale handle). Distinct from 166 because the file exists but is unreadable.

Common situations: Files owned by root from a previous container run, restrictive umasks in CI, state written by a different user, or flaky network filesystems holding the checkout.

Related errors

• could not create output directory
• output directory cannot be a symbolic link
• output file cannot be a symbolic link
• Star count file is not a regular file
• could not atomically replace Star History outputs

AI-assisted analysis of 666ghj/MiroFish@b5b53acc57 (2026-08-14). Data as JSON: /api/errors/098fcdf321eefa0a. Report an issue: GitHub.