affaan-m/ECC · error · ValueError

invalid native snapshot track

Error message

invalid native snapshot track

What it means

Raised by _snapshot while validating the timeline_readback dict of a native snapshot. Every key must be a track name like 'video1' or 'audio2' (prefix 'video'/'audio' followed by a nonzero number) and every value must be a list of clips. This guard exists so downstream binding logic can rely on a well-formed track map.

Solutions

1. Rename snapshot track keys to the exact form 'video<n>' or 'audio<n>' with n starting at 1 (e.g. 'video1').
2. Ensure each track's value is a plain Python list of clip dicts, not a dict or None.
3. Log repr(snapshot['timeline_readback']) and compare each key against re.fullmatch(r"(?:video|audio)[1-9][0-9]*", key) before calling build_application_bundle.

Example fix

// before
snapshot['timeline_readback'] = {'V1': [clip1], 'A1': [clip2]}
// after
snapshot['timeline_readback'] = {'video1': [clip1], 'audio1': [clip2]}

import re
tracks = snapshot.get('timeline_readback', {})
for track, clips in tracks.items():
    assert re.fullmatch(r'(?:video|audio)[1-9][0-9]*', track), f'bad track key: {track}'
    assert isinstance(clips, list), f'track {track} value is not a list'

def is_valid_track_map(tracks) -> bool:
    return (
        isinstance(tracks, dict) and bool(tracks)
        and all(
            isinstance(k, str)
            and re.fullmatch(r'(?:video|audio)[1-9][0-9]*', k) is not None
            and isinstance(v, list)
            for k, v in tracks.items()
        )
    )

try:
    bundle = build_application_bundle(...)
except ValueError as e:
    if 'invalid native snapshot track' in str(e):
        log.error('snapshot timeline_readback malformed', snapshot_tracks=list(snapshot.get('timeline_readback', {})))
    raise

When it happens

Trigger: Calling build_application_bundle when snapshot['timeline_readback'] contains a key that fails the regex (e.g. 'video', 'v1', 'video0', 'video01' is fine as [1-9][0-9]* but 'video00' matches... note 'video0' fails since first digit must be 1-9), or a value that is not a list (dict, None, string).

Common situations: Manually hand-crafting a snapshot for tests, exporting a timeline under a nonstandard naming scheme from a native host app, or parsing a snapshot JSON where track lists were serialized as objects keyed by clip id.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• apply_local needs at least one media clip
• asset contains too few frames
• asset requires verified alpha
• candidate fps/duration/retime ambiguity
• Crop must contain four finite values

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

Appendix: source

Thrown at skills/taste-application/scripts/tasteforge/integration.py:219

        if type(native_fps) not in (str, int, float):
            raise ValueError("native fps missing")
        label = str(native_fps)
        if not re.fullmatch(r"[0-9]{1,9}(?:\.[0-9]{1,12}|/[1-9][0-9]{0,8})?", label):
            raise ValueError("native fps must use a bounded decimal or rational label")
        native_rate = Fraction(ntsc.get(label, label))
        if native_rate != Fraction(*_rate(baseline["fps"])):
            raise ValueError("native fps differs")
    except (ValueError, ZeroDivisionError) as exc:
        raise ValueError("native snapshot fps is missing, invalid or contradictory") from exc
    for cfg, key in [("project_name", "project"), ("timeline_name", "timeline")]:
        if _text(baseline[cfg]) != snapshot.get(key):
            raise ValueError("native snapshot identity mismatch")
    tracks = snapshot.get("timeline_readback")
    if not isinstance(tracks, dict) or not tracks:
        raise ValueError("native clip snapshot required")
    for track, clips in tracks.items():
        if not re.fullmatch(r"(?:video|audio)[1-9][0-9]*", track) or not isinstance(clips, list):
            raise ValueError("invalid native snapshot track")
        for clip in clips:
            _check_clip(clip, bounds)
    return tracks


def _check_clip(clip: Any, bounds: list[int]) -> None:
    required = {"path", "name", "start", "end", "left_offset", "right_offset", "enabled", "properties"}
    if not isinstance(clip, dict) or not required <= clip.keys():
        raise ValueError("native snapshot clip is incomplete")
    _range([clip["start"], clip["end"]], bounds)
    _integer(clip["left_offset"])
    _integer(clip["right_offset"])
    if clip["path"] is not None:
        _text(clip["path"])
    _text(clip["name"])
    if type(clip["enabled"]) is not bool or not isinstance(clip["properties"], dict):
        raise ValueError("native clip state is incomplete")

View on GitHub (pinned to 8321021c54)