LykosAI/StabilityMatrix · error · InvalidOperationException

Klein 4B requires the qwen_3_4b text encoder, which isn't…

Error message

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.

What it means

When the selected Klein UNET is the 4B variant, SelectModels requires a locally installed qwen_3_4b text encoder (matching IsKleinTextEncoder and MatchesEncoderSize("4b")). The manager throws this actionable error rather than substituting a mismatched encoder, which would cause a tensor shape mismatch in the sampler.

Solutions

1. Download qwen_3_4b.safetensors (or _fp4_flux2) from huggingface.co/Comfy-Org/flux2-klein-4B into the TextEncoders folder and refresh the index
2. Select the Klein 9B UNET instead if only the 8b encoder is installed
3. Catch InvalidOperationException and offer an in-app download of the 4b encoder

Example fix

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

bool has4b = clientManager.ClipModels.Any(m => m.Local != null
    && IsKleinTextEncoder(m.FileName) && MatchesEncoderSize(m.FileName, "4b"));
if (!has4b)
    throw new UserDownloadableError("Download qwen_3_4b.safetensors (or _fp4_flux2) into TextEncoders.");

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

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

When it happens

Trigger: Calling SelectModels with preferredEncoderSize "4b" (4B UNET selected) while no ClipModels entry has a local file matching IsKleinTextEncoder with size 4b.

Common situations: User downloaded only the 9B qwen_3_8b encoder; encoder filename variant not recognized by IsKleinTextEncoder; TextEncoders placed in the wrong folder or index not refreshed.

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

• Klein 9B requires the qwen_3_8b text encoder, which isn't…
• Flux.2 Klein UNET model not found
• Flux.2 VAE model not found
• Flux Kontext UNET model not found
• Flux VAE model not found

AI-assisted analysis of LykosAI/StabilityMatrix@af93d6ef57 (2026-09-12). Data as JSON: /api/errors/f20e68ac6e2d5047. 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)