affaan-m/ECC · error · RuntimeError

could not create overlay track

Error message

could not create overlay track

What it means

When the plan requires more overlay tracks than the target currently has, apply_placements calls timeline.AddTrack('video') in a loop and verifies the track count actually increased by exactly one each time. If Resolve's AddTrack returns False or the count does not change, it raises this RuntimeError, because placement cannot proceed without the tracks.

Solutions

1. Pre-add the needed video tracks manually (or via script) before calling apply_placements so AddTrack is never invoked.
2. Reduce the number of overlay tracks in placements so max(track) fits within the current track count.
3. Re-fetch the timeline object from the current project to avoid a stale API handle, then retry.

Example fix

// before
apply_placements(tl, pool, placements, ...)  # needs V6, has V3
// after
while tl.GetTrackCount("video") < max_track:
    tl.AddTrack("video")
apply_placements(tl, pool, placements, ...)

needed = max(e["track"] for e in plan)
if timeline.GetTrackCount("video") < needed:
    print(f"resolve may cap track creation; pre-adding {needed} tracks")

def can_add_track(timeline):
    old = timeline.GetTrackCount("video")
    ok = bool(timeline.AddTrack("video"))
    if not ok or timeline.GetTrackCount("video") != old + 1:
        return False
    return True

try:
    apply_placements(tl, pool, placements, ...)
except RuntimeError as e:
    if "could not create overlay track" in str(e):
        tl = project.GetCurrentTimeline().GetTrackCount() and project.GetCurrentTimeline()
        # re-fetch fresh timeline handle and retry once
    else:
        raise

When it happens

Trigger: Calling apply_placements whose plan targets video track indexes beyond the timeline's track count, and Resolve refuses AddTrack — e.g. hitting the project's/Resolve version's maximum track limit, or the timeline object being stale after undo/redo.

Common situations: Plans computed against a source with many overlay tracks applied to a target capped by Resolve's track limits; scripting a timeline retrieved from a stale resolve object; Resolve version quirks where AddTrack returns non-boolean values.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• base_track_count exceeds target video tracks
• could not append
• target overlay tracks must be empty
• unexpected overlay items after append
• base tracks changed during overlay placement

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

Appendix: source

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

    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 (
            not timeline.AddTrack("video")
            or timeline.GetTrackCount("video") != old_count + 1
        ):
            raise RuntimeError("could not create overlay track")
    appended = []
    for event in plan:
        imported = media_pool.ImportMedia([event["asset"]])
        if not imported or len(imported) != 1:
            raise RuntimeError(f"could not import {event['asset']}")
        items = media_pool.AppendToTimeline(
            [
                {
                    "mediaPoolItem": imported[0],
                    "startFrame": 0,
                    "endFrame": event["frames"] - (source_end_mode == "inclusive"),
                    "mediaType": 1,
                    "trackIndex": event["track"],
                    "recordFrame": event["record_frame"],
                }
            ]
        )
        if not items or len(items) != 1:

View on GitHub (pinned to 8321021c54)