invoke-ai/InvokeAI · error · RuntimeError

Text encoder did not return hidden_states. Ensure output_hid

Error message

Text encoder did not return hidden_states. Ensure output_hidden_states=True is supported by this model.

What it means

The Qwen3 encoder forward is called with output_hidden_states=True; Z-Image needs intermediate hidden states, so _encode_prompt raises a RuntimeError if outputs.hidden_states is missing or None. This happens when the model class does not support the output_hidden_states flag or returns a non-standard output object.

Source

Thrown at invokeai/app/invocations/z_image_text_encoder.py:176

            ):
                removed_text = tokenizer.batch_decode(untruncated_ids[:, max_seq_len - 1 : -1])
                context.logger.warning(
                    f"The following part of your input was truncated because `max_sequence_length` is set to "
                    f"{max_seq_len} tokens: {removed_text}"
                )

            # Get hidden states from the text encoder
            # Use the second-to-last hidden state like diffusers does
            prompt_mask = attention_mask.to(device).bool()
            outputs = text_encoder(
                text_input_ids.to(device),
                attention_mask=prompt_mask,
                output_hidden_states=True,
            )

            # Validate hidden_states output
            if not hasattr(outputs, "hidden_states") or outputs.hidden_states is None:
                raise RuntimeError(
                    "Text encoder did not return hidden_states. "
                    "Ensure output_hidden_states=True is supported by this model."
                )
            if len(outputs.hidden_states) < 2:
                raise RuntimeError(
                    f"Expected at least 2 hidden states from text encoder, got {len(outputs.hidden_states)}. "
                    "This may indicate an incompatible model or configuration."
                )
            prompt_embeds = outputs.hidden_states[-2]

            # Z-Image expects a 2D tensor [seq_len, hidden_dim] with only valid tokens
            # Based on diffusers ZImagePipeline implementation:
            # embeddings_list.append(prompt_embeds[i][prompt_masks[i]])
            # Since batch_size=1, we take the first item and filter by mask
            prompt_embeds = prompt_embeds[0][prompt_mask[0]]

        if not isinstance(prompt_embeds, torch.Tensor):
            raise TypeError(

View on GitHub (pinned to 0b6a024f2f)

Solutions

Load the standard transformers Qwen3 model class which supports output_hidden_states=True.
Check the model's config (e.g. output_hidden_states not disabled) and that its forward supports the kwarg.
Replace quantized/wrapper implementations that drop hidden_states with a standard loading path.
Update transformers to a version where Qwen3 returns ModelOutput with hidden_states.

Defensive patterns

Strategy: validation

Validate before calling

outputs = encoder(**inputs, output_hidden_states=True)
if not hasattr(outputs, "hidden_states") or outputs.hidden_states is None:
    fail_fast("encoder does not emit hidden_states")

Try / catch

try:
    encode(context)
except RuntimeError as e:
    if "did not return hidden_states" in str(e):
        load_standard_qwen3_class()
    else:
        raise

Prevention

Only use Qwen3 model classes that support output_hidden_states=True.
Avoid wrapper/quantization layers that replace the model output object.
Smoke-test the encoder forward once at model install time.

When it happens

Trigger: Calling the Z-Image text encoder where encoder(input_ids=..., attention_mask=..., output_hidden_states=True) returns an object with no hidden_states attribute or hidden_states=None.

Common situations: A substitute/incompatible text encoder model class that ignores output_hidden_states; wrapped or quantized model whose forward returns a custom output type; wrong model class loaded for the Qwen3 submodel.

Related errors

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