invoke-ai/InvokeAI · error · ValueError

Decoder returned an invalid frame for {video_path}

Error message

Decoder returned an invalid frame for {video_path}

What it means

Raised when the decode worker sends a result tagged 'frame' whose payload is not a numpy ndarray, i.e. the worker/parent protocol was violated or the payload was corrupted. In normal operation this is unreachable; it is a defensive invariant check on the IPC queue. It indicates a bug in the worker or a mismatch between worker and library versions.

Source

Thrown at invokeai/app/util/video_thumbnails.py:310

    reader = threading.Thread(target=read_frames, name="video-frame-reader", daemon=True)
    stderr_reader = threading.Thread(target=drain_stderr, name="video-stderr-reader", daemon=True)
    reader.start()
    stderr_reader.start()
    deadline = time.monotonic() + (timeout if first_frame_timeout is None else first_frame_timeout)
    try:
        while True:
            if is_canceled is not None and is_canceled():
                raise CanceledException
            remaining = deadline - time.monotonic()
            if remaining <= 0:
                raise TimeoutError(f"Timed out decoding frames from {video_path}")
            try:
                kind, value = results.get(timeout=min(0.1, remaining))
            except queue.Empty:
                continue
            if kind == "frame":
                if not isinstance(value, np.ndarray):
                    raise ValueError(f"Decoder returned an invalid frame for {video_path}")
                yield value
                deadline = time.monotonic() + timeout
                continue
            try:
                return_code = proc.wait(timeout=min(1, timeout))
            except subprocess.TimeoutExpired as error:
                _terminate_process_tree(proc)
                stderr_reader.join(timeout=1)
                detail = read_stderr()
                message = f"Timed out waiting for video decoder worker for {video_path}"
                raise TimeoutError(f"{message}: {detail}" if detail else message) from error
            if return_code != 0:
                stderr_reader.join(timeout=1)
                detail = read_stderr()
                message = f"Unable to decode video at {video_path}"
                raise ValueError(f"{message}: {detail}" if detail else message) from value
            return
    finally:

View on GitHub (pinned to 0b6a024f2f)

Solutions

  1. Restart the application/worker pool so the spawned decode-worker script matches the installed library version.
  2. Reinstall the package cleanly (pip install --force-reinstall) to remove duplicate/mixed copies in site-packages.
  3. Remove any monkeypatching or custom worker script overrides of the decode command.
  4. If you maintain a fork, keep the worker protocol ('frame' → np.ndarray, 'done'/'error') in sync with the parent.

Example fix

// before
# worker emits frame as list
results.put(("frame", frame.tolist()))  # parent: ValueError invalid frame
// after
results.put(("frame", np.asarray(frame)))  # or stop customizing the worker
Defensive patterns

Strategy: try-catch

Type guard

import numpy as np
def is_valid_frame(value) -> bool:
    return isinstance(value, np.ndarray)

Try / catch

try:
    for frame in iter_video_frames(path):
        ...
except ValueError as e:
    if "invalid frame" in str(e):
        restart_worker_pool()  # version/protocol mismatch

Prevention

When it happens

Trigger: A decode worker built from a different (mixed-install) version of the library emitting frames in an unexpected format; a monkeypatched or replaced worker script; tampering with the results queue protocol in tests.

Common situations: Mixed old/new package installs where the spawned worker script comes from a stale site-packages (e.g. after an upgrade without restarting long-running workers); custom forks altering the frame payload type.

Related errors

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/e7e754e37325725a. Report an issue: GitHub.