affaan-m/ECC · error · RuntimeError

unexpected overlay items after append

Error message

unexpected overlay items after append

What it means

As a final integrity check, apply_placements counts timeline items on every overlay video track and requires the count to equal exactly the number of planned events assigned to that track. Any extra or missing item means Resolve appended something unexpected (or an append silently split/duplicated), so it raises this RuntimeError. Like the base-snapshot check, it protects against silent corruption from Resolve API quirks.

Solutions

1. Undo/rollback the run (timeline was duplicated for this purpose) and inspect where clips actually landed.
2. Prefer single-stream overlay media or pre-trim sources so one import equals one item.
3. Check your Resolve version's AppendToTimeline trackIndex support; add tracks/tracks-empty preconditions manually if needed.

Example fix

// before
# trust AppendToTimeline trackIndex
// after
assert all(len(tl.GetItemListInTrack("video", t)) == expected[t]
           for t in range(base+1, tl.GetTrackCount("video")+1))

for t in range(base + 1, tl.GetTrackCount("video") + 1):
    print(t, len(tl.GetItemListInTrack("video", t)))  # inspect before final run

def track_counts_match(plan, timeline, base):
    return all(
        len(timeline.GetItemListInTrack("video", t))
        == sum(e["track"] == t for e in plan)
        for t in range(base + 1, timeline.GetTrackCount("video") + 1)
    )

try:
    receipt = apply_placements(tl, pool, placements, ...)
except RuntimeError as e:
    if "unexpected overlay items" in str(e):
        print("rollback: discard this duplicate timeline and re-run on a fresh copy")
    else:
        raise

When it happens

Trigger: Resolve placing a clip on a different track than trackIndex requested, AppendToTimeline splitting media into multiple items (multi-track source files), or leftover clips on an overlay track that passed the earlier emptiness check due to a race.

Common situations: Appending stereo/multi-stream sources that Resolve splits across items; concurrent edits by a human while the script runs; Resolve versions where trackIndex in AppendToTimeline is ignored and clips land on the lowest empty track.

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

• base tracks changed during overlay placement
• could not append
• could not create overlay track
• base_track_count exceeds target video tracks
• could not import

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

Appendix: source

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

                "asset": event["asset"],
                "requested": {
                    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)