invoke-ai/InvokeAI · error · ValueError

positive_cap_feats is required when regional_attn_mask is pr

Error message

positive_cap_feats is required when regional_attn_mask is provided

What it means

`patch_transformer_for_regional_prompting` is a generator that only needs a mask plus capped positive-prompt features to build the regional forward; if a `regional_attn_mask` is supplied without `positive_cap_feats`, the regional attention cannot be constructed, so it raises ValueError. Supplying one without the other is always a caller bug since the two are paired inputs.

Source

Thrown at invokeai/backend/z_image/z_image_transformer_patch.py:227

    Args:
        transformer: The ZImageTransformer2DModel instance.
        regional_attn_mask: Regional attention mask of shape (seq_len, seq_len).
                           If None, the transformer is not patched.
        img_seq_len: Number of image tokens.
        positive_cap_feats: The caption-embedding tensor the regional mask was built for.
            Required when ``regional_attn_mask`` is provided; the mask is applied only to
            forward calls whose ``cap_feats`` is this exact object (the conditioned pass).

    Yields:
        The (possibly patched) transformer.
    """
    if regional_attn_mask is None:
        # No regional prompting, use original forward
        yield transformer
        return

    if positive_cap_feats is None:
        raise ValueError("positive_cap_feats is required when regional_attn_mask is provided")

    # Store original forward
    original_forward = transformer.forward

    # Create and bind the regional forward
    regional_fwd = create_regional_forward(original_forward, regional_attn_mask, img_seq_len, positive_cap_feats)
    transformer.forward = lambda *args, **kwargs: regional_fwd(transformer, *args, **kwargs)

    try:
        yield transformer
    finally:
        # Restore original forward
        transformer.forward = original_forward

View on GitHub (pinned to 0b6a024f2f)

Solutions

Pass the corresponding `positive_cap_feats` alongside the regional_attn_mask
If regional prompting is not intended, pass `regional_attn_mask=None` to get the unpatched original forward
Fix the upstream call site (e.g. _run_diffusion) to always produce both mask and capped features together

Example fix

// before
yield from patch_transformer_for_regional_prompting(transformer, mask, img_seq_len, None)  # ValueError
// after
yield from patch_transformer_for_regional_prompting(transformer, mask, img_seq_len, positive_cap_feats)

Defensive patterns

Strategy: validation

Validate before calling

def validate_regional_args(regional_attn_mask, positive_cap_feats):
    if regional_attn_mask is not None and positive_cap_feats is None:
        raise ValueError("positive_cap_feats must accompany regional_attn_mask")

validate_regional_args(regional_attn_mask, positive_cap_feats)

Try / catch

try:
    for t in patch_transformer_for_regional_prompting(transformer, mask, img_seq_len, cap_feats):
        run(t)
except ValueError as e:
    if "positive_cap_feats is required" in str(e):
        for t in patch_transformer_for_regional_prompting(transformer, None, img_seq_len, None):
            run(t)  # fall back to non-regional forward
    else:
        raise

Prevention

Always compute regional_attn_mask and positive_cap_feats together in one function
Default both to None and pass them as a pair from call sites
Add an early assert that both are None or both are non-None
Cover the regional-prompting call path with a smoke test

When it happens

Trigger: Calling `patch_transformer_for_regional_prompting(transformer, regional_attn_mask=<mask>, img_seq_len=..., positive_cap_feats=None)` — passing a non-None mask while `positive_cap_feats` is None or omitted.

Common situations: A caller computes the attention mask but fails to compute/forward the capped positive prompt features; partially wiring regional prompting so only the mask argument is populated; refactoring that dropped the positive_cap_feats argument.

Related errors

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