affaan-m/ECC · critical · RuntimeError

base tracks changed during overlay placement

Error message

base tracks changed during overlay placement

What it means

apply_placements snapshots the base tracks (tracks 1..base_track_count) before appending, then re-snapshots after all placements and property writes. If the two snapshots differ, the base edit was disturbed and it raises this RuntimeError. This guarantees the overlay application is non-destructive to the underlying timeline content.

Solutions

1. Ensure no one (or no other script) touches the timeline while apply_placements runs; run against a private duplicate timeline.
2. Disable ripple/auto-select behaviors in the Resolve project before running.
3. Re-raise with a diff of before/after snapshots to identify which base clip moved, then correct the placement plan.

Example fix

// before
apply_placements(shared_tl, pool, placements, ...)
// after
target = shared_tl.CreateDuplicateTimeline("apply-private")
apply_placements(target, pool, placements, ...)

snapshot_before = [(i.GetName(), i.GetStart(), i.GetEnd())
                   for t in range(1, base+1)
                   for i in tl.GetItemListInTrack("video", t)]
# compare after run; if changed, discard the timeline copy

def base_tracks_stable(before, after):
    return before == after

try:
    apply_placements(target, pool, placements, ...)
except RuntimeError as e:
    if "base tracks changed" in str(e):
        print("base edit disturbed; delete duplicate and investigate ripple/auto-select settings")
    else:
        raise

When it happens

Trigger: Resolve moving/ripple-editing base clips when appending to upper tracks (ripple/insert behavior active), a user editing the timeline concurrently, or AppendToTimeline without explicit trackIndex landing on base tracks and shifting them.

Common situations: Timeline 'auto track selector' or ripple settings altered by the operator; another operator/script editing the shared project during the run; base clips whose properties (opacity) were overwritten by the script writing to the wrong item index.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• unexpected overlay items after append
• base_track_count exceeds target video tracks
• could not append
• could not create overlay track
• target overlay tracks must be empty

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

Appendix: source

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

                    key: event[key]
                    for key in (
                        "record_frame",
                        "frames",
                        "track",
                        "opacity",
                        "composite",
                    )
                },
                "actual": actual,
            }
        )
    for track in range(base_track_count + 1, timeline.GetTrackCount("video") + 1):
        if len(_items(timeline, "video", track)) != sum(
            e["track"] == track for e in plan
        ):
            raise RuntimeError("unexpected overlay items after append")
    if before != _base_snapshot(timeline, base_track_count):
        raise RuntimeError("base tracks changed during overlay placement")
    return {
        "timeline": name,
        "source_timeline": source_timeline,
        "source_end_mode": source_end_mode,
        "base_track_count": base_track_count,
        "fps": float(_fps(fps)),
        "placements": receipts,
        "preservation": {"base_tracks_match": True},
    }

View on GitHub (pinned to 8321021c54)