affaan-m/ECC · error · ValueError

source_timeline must be explicit

Error message

source_timeline must be explicit

What it means

The source timeline name must be a non-empty explicit string. apply_placements compares the target timeline's name against it to enforce the target is a distinct versioned copy, so a missing/blank source name cannot be tolerated. Validated before any mutation.

Solutions

1. Pass the exact source timeline name string, e.g. source_timeline="master_v3"
2. Fix the caller to extract timeline.GetName() if you have an object
3. Check config/env plumbing so the name isn't dropped before the call

Example fix

// before
apply_placements(timeline, pool, placements, source_timeline=source_tl_obj)
// after
apply_placements(timeline, pool, placements, source_timeline=source_tl_obj.GetName())

if not isinstance(source_timeline, str) or not source_timeline.strip():
    raise ValueError("source_timeline must be a non-empty string name")

def is_nonempty_str(v) -> bool:
    return isinstance(v, str) and bool(v.strip())

try:
    apply_placements(..., source_timeline=name)
except ValueError as exc:
    if "source_timeline" in str(exc):
        print("Pass the source timeline NAME, not an object or empty value")
    raise

When it happens

Trigger: Calling apply_placements/apply with source_timeline=None, "", a non-string (e.g. a timeline object), or whitespace-only value.

Common situations: CLI flag not passed through to the function; config key read from an unset env var; refactoring where the timeline object was passed instead of its name.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• at least one non-empty
• image_to_3d needs at least one image
• Invalid value: expected a path
• references exceed bounded limits
• must use non-empty key=value form

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

Appendix: source

Thrown at skills/taste-application/scripts/tasteforge/resolve.py:253

    placements,
    *,
    source_timeline,
    source_end_mode,
    fps,
    base_track_count,
    probe=probe_asset,
):
    """Append and verify overlays; returns an in-memory placement receipt only.

    This does not save/export/render a project. Supply the selected target's
    media pool. Existing overlay tracks must be empty; base tracks are preserved.
    source_end_mode is required: use the endpoint convention verified on this
    Resolve host. No automatic retry occurs if that convention is incorrect.
    """
    if source_end_mode not in ("inclusive", "exclusive"):
        raise ValueError("source_end_mode must be inclusive or exclusive")
    if not isinstance(source_timeline, str) or not source_timeline:
        raise ValueError("source_timeline must be explicit")
    name = timeline.GetName()
    if not name or name == source_timeline:
        raise ValueError("target must be a distinct versioned timeline")
    plan = allocate_placements(
        placements, fps=fps, base_track_count=base_track_count, probe=probe
    )
    if _fps(timeline.GetSetting("timelineFrameRate")) != _fps(fps):
        raise ValueError("target timeline fps mismatch")
    count = timeline.GetTrackCount("video")
    if count < base_track_count:
        raise ValueError("base_track_count exceeds target video tracks")
    for track in range(base_track_count + 1, count + 1):
        if _items(timeline, "video", track):
            raise ValueError("target overlay tracks must be empty")
    before = _base_snapshot(timeline, base_track_count)
    for _ in range(count, max(event["track"] for event in plan)):
        old_count = timeline.GetTrackCount("video")
        if (

View on GitHub (pinned to 8321021c54)