LykosAI/StabilityMatrix · error · InvalidOperationException

Klein 9B requires the qwen_3_8b text encoder, which isn't…

Error message

Klein 9B requires the qwen_3_8b text encoder, which isn't installed. Download qwen_3_8b_fp8mixed.safetensors (or _fp4mixed / _bf16) from huggingface.co/Comfy-Org/flux2-klein-9B and place it in your TextEncoders folder.

What it means

When the selected Klein UNET is the 9B variant, SelectModels requires a locally installed qwen_3_8b text encoder (matching IsKleinTextEncoder and MatchesEncoderSize("8b")). Pairing the wrong encoder size causes a tensor shape mismatch in the sampler, so the manager fails fast with this actionable message listing the exact download source.

Solutions

Download qwen_3_8b_fp8mixed.safetensors (or _fp4mixed / _bf16) from huggingface.co/Comfy-Org/flux2-klein-9B into the TextEncoders folder and refresh the index
Select the Klein 4B UNET instead if the 8b encoder is unavailable
Catch InvalidOperationException and offer an in-app download of the required encoder

Example fix

// before
var models = flux2KleinModelManager.SelectModels(); // throws for 9B without 8b encoder
// after
var has8b = clientManager.ClipModels.Any(m => m.Local != null && IsKleinTextEncoder(m.FileName) && MatchesEncoderSize(m.FileName, "8b"));
if (!has8b)
{
    await sharedFolders.DownloadModelAsync(Flux2Klein9BTextEncoderUri, SharedFolderType.TextEncoders);
}
var models = flux2KleinModelManager.SelectModels();

Defensive patterns

Strategy: validation

Validate before calling

bool has8b = clientManager.ClipModels.Any(m => m.Local != null
    && IsKleinTextEncoder(m.FileName) && MatchesEncoderSize(m.FileName, "8b"));
if (!has8b)
    throw new UserDownloadableError("Download qwen_3_8b_fp8mixed.safetensors (or _fp4mixed/_bf16) into TextEncoders.");

Type guard

bool HasEncoder(IEnumerable<HybridModelFile> clips, string size) => clips.Any(m => m.Local != null && IsKleinTextEncoder(m.FileName) && MatchesEncoderSize(m.FileName, size));

Try / catch

try
{
    var models = flux2KleinModelManager.SelectModels();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("qwen_3_8b"))
{
    // start download of qwen_3_8b encoder
}

Prevention

Match encoder size to the selected UNET variant (8b for 9B, 4b for 4B)
Pre-download both encoder sizes if users may switch UNET variants
Verify encoder files with recognized naming variants only

When it happens

Trigger: Calling SelectModels with preferredEncoderSize "8b" (9B UNET selected) while no ClipModels entry has a local file that both matches IsKleinTextEncoder and MatchesEncoderSize "8b".

Common situations: User downloaded only the 4B qwen_3_4b encoder; encoder file named with an unrecognized variant so it doesn't match; TextEncoders folder not scanned/refreshed after download.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of LykosAI/StabilityMatrix@af93d6ef57 (2026-09-12). Data as JSON: /api/errors/2766bbf398674a7c. Report an issue: GitHub.

Appendix: source

Thrown at StabilityMatrix.Avalonia/Services/Flux2KleinModelManager.cs:183

        var vaeModel =
            clientManager.VaeModels.FirstOrDefault(m => m.Local != null && IsFlux2Vae(m.FileName))
            ?? throw new InvalidOperationException("Flux.2 VAE model not found");

        // Match the text encoder to the selected UNET variant. The 4B UNET expects
        // qwen_3_4b (~4B params, hidden_dim 2560) and the 9B UNET expects qwen_3_8b
        // (~8B params, hidden_dim 4096) — pairing the wrong size produces a tensor
        // shape mismatch deep inside the sampler, so we fail fast here with a clear
        // message rather than silently substituting the other size.
        var preferredEncoderSize = GetExpectedEncoderSize(unetModel);

        var clipModel =
            clientManager.ClipModels.FirstOrDefault(m =>
                m.Local != null
                && IsKleinTextEncoder(m.FileName)
                && MatchesEncoderSize(m.FileName, preferredEncoderSize)
            )
            ?? throw new InvalidOperationException(
                preferredEncoderSize == "8b"
                    ? "Klein 9B requires the qwen_3_8b text encoder, which isn't installed. Download qwen_3_8b_fp8mixed.safetensors (or _fp4mixed / _bf16) from huggingface.co/Comfy-Org/flux2-klein-9B and place it in your TextEncoders folder."
                    : "Klein 4B requires the qwen_3_4b text encoder, which isn't installed. Download qwen_3_4b.safetensors (or _fp4_flux2) from huggingface.co/Comfy-Org/flux2-klein-4B and place it in your TextEncoders folder."
            );

        return new SelectedModels(unetModel, vaeModel, clipModel);
    }

    /// <summary>
    /// Detects which Qwen3 text-encoder size a Klein UNET (or Klein-derived merge/fine-tune)
    /// pairs with. Checks the connected CivitAI metadata first — `BaseModel`, `ModelName`,
    /// `VersionName`, `VersionDescription`, and `TrainedWords` — because filenames on
    /// community merges often don't include a "9b" / "4b" hint. Falls back to the filename,
    /// then defaults to "4b" (matches the auto-downloaded Apache 2.0 Klein 4B variant).
    /// </summary>
    internal static string GetExpectedEncoderSize(HybridModelFile unetModel)
    {
        var info = unetModel.Local?.ConnectedModelInfo;

View on GitHub (pinned to af93d6ef57)