{"record":{"id":"f20e68ac6e2d5047","repo":"LykosAI/StabilityMatrix","slug":"klein-4b-requires-the-qwen-3-4b-text-encoder-which-isn-t","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"StabilityMatrix.Avalonia/Services/Flux2KleinModelManager.cs","lineNumber":183,"sourceCode":"\n        var vaeModel =\n            clientManager.VaeModels.FirstOrDefault(m => m.Local != null && IsFlux2Vae(m.FileName))\n            ?? throw new InvalidOperationException(\"Flux.2 VAE model not found\");\n\n        // Match the text encoder to the selected UNET variant. The 4B UNET expects\n        // qwen_3_4b (~4B params, hidden_dim 2560) and the 9B UNET expects qwen_3_8b\n        // (~8B params, hidden_dim 4096) — pairing the wrong size produces a tensor\n        // shape mismatch deep inside the sampler, so we fail fast here with a clear\n        // message rather than silently substituting the other size.\n        var preferredEncoderSize = GetExpectedEncoderSize(unetModel);\n\n        var clipModel =\n            clientManager.ClipModels.FirstOrDefault(m =>\n                m.Local != null\n                && IsKleinTextEncoder(m.FileName)\n                && MatchesEncoderSize(m.FileName, preferredEncoderSize)\n            )\n            ?? throw new InvalidOperationException(\n                preferredEncoderSize == \"8b\"\n                    ? \"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.\"\n                    : \"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.\"\n            );\n\n        return new SelectedModels(unetModel, vaeModel, clipModel);\n    }\n\n    /// <summary>\n    /// Detects which Qwen3 text-encoder size a Klein UNET (or Klein-derived merge/fine-tune)\n    /// pairs with. Checks the connected CivitAI metadata first — `BaseModel`, `ModelName`,\n    /// `VersionName`, `VersionDescription`, and `TrainedWords` — because filenames on\n    /// community merges often don't include a \"9b\" / \"4b\" hint. Falls back to the filename,\n    /// then defaults to \"4b\" (matches the auto-downloaded Apache 2.0 Klein 4B variant).\n    /// </summary>\n    internal static string GetExpectedEncoderSize(HybridModelFile unetModel)\n    {\n        var info = unetModel.Local?.ConnectedModelInfo;","sourceCodeStart":165,"sourceCodeEnd":201,"githubUrl":"https://github.com/LykosAI/StabilityMatrix/blob/af93d6ef57c01cd890d7e0ad0a9ea8c9fcda3002/StabilityMatrix.Avalonia/Services/Flux2KleinModelManager.cs#L165-L201","documentation":"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.","triggerScenarios":"Calling SelectModels with preferredEncoderSize \"4b\" (4B UNET selected) while no ClipModels entry has a local file matching IsKleinTextEncoder with size 4b.","commonSituations":"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.","solutions":["Download qwen_3_4b.safetensors (or _fp4_flux2) from huggingface.co/Comfy-Org/flux2-klein-4B into the TextEncoders folder and refresh the index","Select the Klein 9B UNET instead if only the 8b encoder is installed","Catch InvalidOperationException and offer an in-app download of the 4b encoder"],"exampleFix":"// before\nvar models = flux2KleinModelManager.SelectModels(); // throws for 4B without 4b encoder\n// after\nvar has4b = clientManager.ClipModels.Any(m => m.Local != null && IsKleinTextEncoder(m.FileName) && MatchesEncoderSize(m.FileName, \"4b\"));\nif (!has4b)\n{\n    await sharedFolders.DownloadModelAsync(Flux2Klein4BTextEncoderUri, SharedFolderType.TextEncoders);\n}\nvar models = flux2KleinModelManager.SelectModels();","handlingStrategy":"validation","validationCode":"bool has4b = clientManager.ClipModels.Any(m => m.Local != null\n    && IsKleinTextEncoder(m.FileName) && MatchesEncoderSize(m.FileName, \"4b\"));\nif (!has4b)\n    throw new UserDownloadableError(\"Download qwen_3_4b.safetensors (or _fp4_flux2) into TextEncoders.\");","typeGuard":"bool HasEncoder(IEnumerable<HybridModelFile> clips, string size) => clips.Any(m => m.Local != null && IsKleinTextEncoder(m.FileName) && MatchesEncoderSize(m.FileName, size));","tryCatchPattern":"try\n{\n    var models = flux2KleinModelManager.SelectModels();\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"qwen_3_4b\"))\n{\n    // start download of qwen_3_4b encoder\n}","preventionTips":["Match encoder size to the selected UNET variant (4b for 4B)","Pre-download both encoder sizes to allow variant switching","Confirm encoder files land in the scanned TextEncoders folder"],"tags":["comfyui","text-encoder","models"],"backgroundTag":"resource-not-found","analyzedSha":"af93d6ef57c01cd890d7e0ad0a9ea8c9fcda3002","analyzedAt":"2026-09-12T19:02:43.389Z","contentChangedAt":"2026-09-12T19:02:43.389Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}