affaan-m/ECC · error · ValueError

all overlays must be readable local files

Error message

all overlays must be readable local files

What it means

forge() validates every entry of the optional overlays list: each overlay must be an existing regular local file. If any overlay path is missing or is not a file, it raises ValueError before processing begins.

Solutions

1. Filter to existing files first: [o for o in overlays if Path(o).is_file()].
2. Expand globs explicitly before the call: sorted(glob('overlays/*.png')).
3. Regenerate the overlay assets if an upstream step failed to create them.
4. Use absolute paths for overlay assets.

Example fix

# before
forge('noir', takes, overlays=['overlays/*.png'], out='edit.mp4')  # glob not expanded

# after
import glob
overlays = [o for o in sorted(glob.glob('overlays/*.png')) if Path(o).is_file()]
forge('noir', takes, overlays=overlays, out='edit.mp4')

from pathlib import Path

def overlays_ok(overlays):
    return all(Path(o).is_file() for o in (overlays or []))

try:
    forge(genre, takes, overlays=overlays, out=out)
except ValueError as e:
    if 'overlays' in str(e):
        print('missing overlays:', [o for o in overlays if not Path(o).is_file()])
    raise

When it happens

Trigger: Passing overlays=['img/watermark.png'] where the PNG was deleted or renamed; passing a directory; passing remote URLs or glob-unexpanded patterns ('*.png') as overlay entries.

Common situations: Assets folder reorganized so overlay paths changed; forgetting that glob patterns are not expanded when calling forge() programmatically; overlays generated by a previous step that failed silently.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• all takes must be readable local files
• base video must be a readable local file
• output already exists; choose a new --out
• output must have a video suffix distinct from…
• Path does not exist

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/8d2e75e3819dc2e2. Report an issue: GitHub.

Appendix: source

Thrown at skills/taste-application/scripts/forge.py:75

    overlay_every: int = 4,
    overlay_opacity: float = 0.3,
    duration: float | None = None,
    strength: float = 1.0,
    grade_base: bool = True,
    width: int | None = None,
    height: int | None = None,
    work: str = "out/forge_work",
    plan: list[dict] | None = None,
    fps: float | None = None,
) -> Path:
    out_path = Path(out)
    validate_output(out_path)
    if not takes or any(not Path(t).is_file() for t in takes):
        raise ValueError("all takes must be readable local files")
    if base_video and not Path(base_video).is_file():
        raise ValueError("base video must be a readable local file")
    if any(not Path(o).is_file() for o in (overlays or [])):
        raise ValueError("all overlays must be readable local files")
    if fps is not None and (not math.isfinite(fps) or fps <= 0):
        raise ValueError("fps must be finite and positive")
    sp = pack_mod.load(genre, root=root)
    tgt = grade_mod.load_stats(sp.grade_path)
    cad = cad_mod.load(sp.cadence_path)

    # Geometry comes from the first take unless overridden; everything else is
    # normalized to it so concat does not silently fail on a size mismatch.
    info0 = frame_mod.probe(takes[0])
    W = width or info0.width
    H = height or info0.height
    FPS = fps if fps is not None else info0.fps
    if not math.isfinite(FPS) or FPS <= 0:
        raise ValueError("source fps must be finite and positive; provide --fps")
    if W <= 0 or H <= 0:
        raise ValueError("output width and height must be positive")
    # Prior timelines reference these shot files. Each run owns a fresh child,
    # including failed runs, so retries cannot erase an existing edit.

View on GitHub (pinned to 8321021c54)