invoke-ai/InvokeAI · error · BatchZippedLengthError

Zipped batch items must all have the same length

Error message

Zipped batch items must all have the same length

What it means

When a batch uses collect-type 'zip' (BatchZipped), every batch_data list must contain item lists of equal length so items can be paired index-by-index. The BatchZippedLengthError is raised by the validate_lengths field validator when any list's item count differs from the first list's count.

Source

Thrown at invokeai/app/services/session_queue/session_queue_common.py:102

    )
    data: Optional[BatchDataCollection] = Field(default=None, description="The batch data collection.")
    graph: Graph = Field(description="The graph to initialize the session with")
    workflow: Optional[WorkflowWithoutID] = Field(
        default=None, description="The workflow to initialize the session with"
    )
    runs: int = Field(
        default=1, ge=1, description="Int stating how many times to iterate through all possible batch indices"
    )

    @field_validator("data")
    def validate_lengths(cls, v: Optional[BatchDataCollection]):
        if v is None:
            return v
        for batch_data_list in v:
            first_item_length = len(batch_data_list[0].items) if batch_data_list and batch_data_list[0].items else 0
            for i in batch_data_list:
                if len(i.items) != first_item_length:
                    raise BatchZippedLengthError("Zipped batch items must all have the same length")
        return v

    @field_validator("data")
    def validate_types(cls, v: Optional[BatchDataCollection]):
        if v is None:
            return v
        for batch_data_list in v:
            for datum in batch_data_list:
                if not datum.items:
                    continue

                # Special handling for numbers - they can be mixed
                # TODO(psyche): Update BatchDatum to have a `type` field to specify the type of the items, then we can have strict float and int fields
                if all(isinstance(item, (int, float)) for item in datum.items):
                    continue

                # Get the type of the first item in the list
                first_item_type = type(datum.items[0])

View on GitHub (pinned to 0b6a024f2f)

Solutions

  1. Pad or trim collections so every zipped batch_data list has the same number of items
  2. Check the script generating the batch data for off-by-one or filtering differences between collections
  3. Switch the batch data to 'unzip' collect type if independent expansion is intended
  4. Validate item counts client-side before creating the Batch

Example fix

// before
{"collect": "zip", "items": ["p1", "p2", "p3"]} paired with 4 images
// after: lengths must match
{"collect": "zip", "items": ["p1", "p2", "p3"]} paired with 3 images
Defensive patterns

Strategy: validation

Validate before calling

def validate_zip_lengths(data):
    for batch_data_list in data:
        lengths = {len(d.items) for d in batch_data_list if d.items}
        if len(lengths) > 1:
            raise ValueError(f"Zipped batch collections must have equal lengths, got {sorted(lengths)}.")

Type guard

def is_zip_safe(batch_data_list) -> bool:
    lengths = {len(d.items) for d in batch_data_list if d.items}
    return len(lengths) <= 1

Try / catch

try:
    batch = Batch(**batch_dict)
except BatchZippedLengthError as e:
    logger.error(f"Zip length mismatch: {e}")
    # pad/trim collections and rebuild

Prevention

When it happens

Trigger: Building a Batch configuration with data collections where e.g. one image collection has 4 items and a paired prompt collection has 3 items, then validating/enqueuing the batch session.

Common situations: Hand-editing batch JSON, generating batch data from arrays of unequal length in a script, or appending items to one collection but not its zip partner.

Related errors

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