{"record":{"id":"739283aafda5e03a","repo":"invoke-ai/InvokeAI","slug":"positive-cap-feats-is-required-when-regional-attn","errorCode":null,"errorMessage":"positive_cap_feats is required when regional_attn_mask is provided","messagePattern":"positive_cap_feats is required when regional_attn_mask is provided","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/z_image/z_image_transformer_patch.py","lineNumber":227,"sourceCode":"    Args:\n        transformer: The ZImageTransformer2DModel instance.\n        regional_attn_mask: Regional attention mask of shape (seq_len, seq_len).\n                           If None, the transformer is not patched.\n        img_seq_len: Number of image tokens.\n        positive_cap_feats: The caption-embedding tensor the regional mask was built for.\n            Required when ``regional_attn_mask`` is provided; the mask is applied only to\n            forward calls whose ``cap_feats`` is this exact object (the conditioned pass).\n\n    Yields:\n        The (possibly patched) transformer.\n    \"\"\"\n    if regional_attn_mask is None:\n        # No regional prompting, use original forward\n        yield transformer\n        return\n\n    if positive_cap_feats is None:\n        raise ValueError(\"positive_cap_feats is required when regional_attn_mask is provided\")\n\n    # Store original forward\n    original_forward = transformer.forward\n\n    # Create and bind the regional forward\n    regional_fwd = create_regional_forward(original_forward, regional_attn_mask, img_seq_len, positive_cap_feats)\n    transformer.forward = lambda *args, **kwargs: regional_fwd(transformer, *args, **kwargs)\n\n    try:\n        yield transformer\n    finally:\n        # Restore original forward\n        transformer.forward = original_forward\n","sourceCodeStart":209,"sourceCodeEnd":241,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/z_image/z_image_transformer_patch.py#L209-L241","documentation":"`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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nyield from patch_transformer_for_regional_prompting(transformer, mask, img_seq_len, None)  # ValueError\n// after\nyield from patch_transformer_for_regional_prompting(transformer, mask, img_seq_len, positive_cap_feats)","handlingStrategy":"validation","validationCode":"def validate_regional_args(regional_attn_mask, positive_cap_feats):\n    if regional_attn_mask is not None and positive_cap_feats is None:\n        raise ValueError(\"positive_cap_feats must accompany regional_attn_mask\")\n\nvalidate_regional_args(regional_attn_mask, positive_cap_feats)","typeGuard":null,"tryCatchPattern":"try:\n    for t in patch_transformer_for_regional_prompting(transformer, mask, img_seq_len, cap_feats):\n        run(t)\nexcept ValueError as e:\n    if \"positive_cap_feats is required\" in str(e):\n        for t in patch_transformer_for_regional_prompting(transformer, None, img_seq_len, None):\n            run(t)  # fall back to non-regional forward\n    else:\n        raise","preventionTips":["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"],"tags":["value-error","regional-prompting","argument-validation","z-image"],"backgroundTag":"required-argument-missing","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}