666ghj/MiroFish · error · StarHistoryError

{label} is missing

Error message

{label} is missing

What it means

_read_limited wraps file reads; FileNotFoundError is mapped to '{label} is missing'. In practice label is 'history state' (from load_state reading .github/star-history/history.json), so the message reads 'history state is missing'. The tool treats a absent state file as an error rather than silently starting fresh.

Source

Thrown at scripts/star_history.py:502

            current = current / part
            if current.is_symlink():
                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:

View on GitHub (pinned to b5b53acc57)

Solutions

  1. Run the fetch/backfill step first to generate .github/star-history/history.json before loading
  2. Confirm the workspace argument points at the checkout containing .github
  3. If the file was deleted, restore from git: git checkout -- .github/star-history/history.json
  4. Check .gitignore is not excluding the state path in shared environments

Example fix

# before
state = load_state(workspace)
# after
generate_state(workspace, github, now=...)  # produces history.json first
state = load_state(workspace)
Defensive patterns

Strategy: validation

Validate before calling

def state_exists(ws: Path) -> bool:
    return (ws / Path('.github/star-history/history.json')).is_file()

Type guard

def ready_to_load(ws: Path) -> bool:
    p = ws / Path('.github/star-history/history.json')
    return p.exists() and not p.is_symlink()

Try / catch

try:
    state = load_state(ws)
except StarHistoryError as e:
    if str(e) == "history state is missing":
        state = generate_state(ws, github)  # first-run bootstrap
    else: raise

Prevention

When it happens

Trigger: Calling load_state(workspace) on a workspace that has never run the backfill/render steps, after the state file was deleted or gitignored, or when the wrong workspace path was passed so the relative join misses the real file.

Common situations: First run on a fresh clone, CI pipelines that clean untracked files, accidentally passing repo parent instead of repo root, or moving the repo without .github.

Related errors

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