Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: load the retired FLUX.3 full copies through their base (#14173)

Daniel Han83dc7f891cac
diff --git a/studio/backend/core/inference/diffusion_families.py b/studio/backend/core/inference/diffusion_families.py
index e913454b6ab..ea7f7c17442 100644
--- a/studio/backend/core/inference/diffusion_families.py
+++ b/studio/backend/core/inference/diffusion_families.py
@@ -1581,6 +1581,33 @@ _GATED_UPSTREAMS: frozenset[str] = frozenset(
u.lower() for u, _m in _GATED_MIRROR_PAIRS + _VIDEO_GATED_MIRROR_PAIRS
)
+# Retired full copies of a gated base: ``unsloth/flux-3-image-klein[-base]`` hold the whole BFL repo (single files and
+# diffusers folders). They stay up for existing links, but Studio's copy of those files now lives in the -FP8 repo
+# (``_GATED_MIRROR_PAIRS``), so a load that names one is the same load as a pick of the base it copies.
+_RETIRED_FULL_COPIES: dict[str, str] = {
+ "unsloth/flux-3-image-klein": "black-forest-labs/flux-3-image-klein",
+ "unsloth/flux-3-image-klein-base": "black-forest-labs/flux-3-image-klein-base",
+}
+
+
+_RETIRED_COPY_SNAPSHOT = re.compile(
+ r"(?:^|[\\/])models--unsloth--(flux-3-image-klein(?:-base)?)[\\/]snapshots[\\/][^\\/]+[\\/]?$",
+ re.IGNORECASE,
+)
+
+
+def retired_full_copy_base(repo_id: Optional[str]) -> Optional[str]:
+ """The base a retired full copy stands for (Studio loads it through that base's mirror), else None. Its id, or an
+ HF-cache snapshot of it (``.../models--unsloth--flux-3-image-klein/snapshots/<sha>``)."""
+ key = (repo_id or "").strip()
+ base = _RETIRED_FULL_COPIES.get(key.lower())
+ if base is None:
+ snapshot = _RETIRED_COPY_SNAPSHOT.search(key)
+ base = (
+ _RETIRED_FULL_COPIES.get(f"unsloth/{snapshot.group(1).lower()}") if snapshot else None
+ )
+ return base
+
# Repo id (lowercased) -> the commit a load's plan pinned it to, for the duration of that load's assembly. Set only by
# ``pinned_repo_revision`` around a video load; every hub-id CONFIG read of a base repo (encoder / VAE / transformer
diff --git a/studio/backend/core/inference/media_auto_switch.py b/studio/backend/core/inference/media_auto_switch.py
index ffc41e75a14..d68ad67f632 100644
--- a/studio/backend/core/inference/media_auto_switch.py
+++ b/studio/backend/core/inference/media_auto_switch.py
@@ -118,6 +118,41 @@ def resident_answers_media_request(
return pick is not None and satisfied_by(resident, name, pick)
+def _resolve_pick(owner: str, name: str, task: str) -> Optional[MediaModelPick]:
+ """The downloaded model *name* refers to. A retired FLUX.3 full copy that is not downloaded itself answers with
+ what replaced it when that is downloaded: the base it copies, which Studio stages in that base's -FP8 mirror."""
+ pick = resolve_local_media_model(name, task = task)
+ if pick is not None or owner != DIFFUSION:
+ return pick
+ from core.inference.diffusion_families import mirror_repo, retired_full_copy_base
+
+ base = retired_full_copy_base(name)
+ if base is None:
+ return None
+ if any(
+ c and resolve_local_media_model(c, task = task) is not None for c in (base, mirror_repo(base))
+ ):
+ # Under the base's identity, as the load route publishes it: locality is planned for the base (its cached
+ # mirror), and a base the Images page already loaded answers the request without a reload.
+ return MediaModelPick(base, base, None, "pipeline")
+ return None
+
+
+def _retired_copy_as_base(pick: MediaModelPick) -> MediaModelPick:
+ """A downloaded retired FLUX.3 full copy as the load will read it: the pick of the base it copies, which
+ ``DiffusionLoadRequest`` redirects it to. So locality is proven for the files that load fetches (the -FP8 mirror's),
+ not the copy's snapshot, and the resident match compares the id the status publishes."""
+ from core.inference.diffusion_families import retired_full_copy_base
+
+ base = retired_full_copy_base(pick.model_id)
+ if base is None:
+ return pick
+ single = (pick.gguf_filename or "").replace("\\", "/")
+ if single and single != "model.safetensors":
+ return pick
+ return MediaModelPick(base, base, None, "pipeline")
+
+
async def _require_local(
owner: str,
pick: MediaModelPick,
@@ -459,7 +494,7 @@ async def maybe_auto_switch_media_model(
# off the loop: a cold index walks the model roots and reads gguf headers
pick = await bounded(
- asyncio.to_thread(resolve_local_media_model, name, task = task),
+ asyncio.to_thread(_resolve_pick, owner, name, task),
deadline,
kind = kind,
openai_errors = openai_errors,
@@ -481,6 +516,9 @@ async def maybe_auto_switch_media_model(
code = "model_not_found",
)
+ if owner == DIFFUSION:
+ pick = _retired_copy_as_base(pick)
+
# before anything is evicted: the load would otherwise finish and be refused for lacking txt2img
if owner == DIFFUSION and await asyncio.to_thread(is_edit_only, pick):
raise refuse(
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index 5c0992b2448..970f5105218 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -4754,6 +4754,39 @@ class DiffusionLoadRequest(BaseModel):
seen.add(spec.id)
return value
+ @model_validator(mode = "after")
+ def _redirect_retired_full_copy(self) -> "DiffusionLoadRequest":
+ # unsloth/flux-3-image-klein[-base] are retired full copies of the gated BFL repos; Studio's copy of those files
+ # lives in the -FP8 repo now. Naming one, or a downloaded snapshot of one (its path, with the copy as the display
+ # id), loads the base it copies, exactly as the picker's own row does, so the load fetches what the plan prices
+ # (hosted encoder, mirror folders) instead of the whole bf16 repo. Its root bf16 ``model.safetensors`` is that
+ # base's transformer, so a single-file pick of it is the pipeline load; supplied encoder / VAE files or another
+ # companion base make it a different build, which stays on the copy.
+ from core.inference.diffusion_families import retired_full_copy_base
+
+ base = retired_full_copy_base(self.model_path) or retired_full_copy_base(
+ self.display_repo_id
+ )
+ if base is not None:
+ single = (self.gguf_filename or "").strip().replace("\\", "/")
+ if not single:
+ self.model_path, self.display_repo_id = base, None
+ elif (
+ single == "model.safetensors"
+ and self.text_encoder_file is None
+ and self.vae_file is None
+ # An explicit companion base other than the one it copies is a different build too.
+ and (
+ not (self.base_repo or "").strip()
+ or (retired_full_copy_base(self.base_repo) or self.base_repo) == base
+ )
+ ):
+ self.model_path, self.display_repo_id = base, None
+ self.gguf_filename, self.model_kind = None, "pipeline"
+ if retired_full_copy_base(self.base_repo) is not None:
+ self.base_repo = retired_full_copy_base(self.base_repo)
+ return self
+
class LoraSpec(BaseModel):
"""One LoRA adapter to apply for a generation, referenced by its discovery id.
diff --git a/studio/backend/tests/test_diffusion_routes.py b/studio/backend/tests/test_diffusion_routes.py
index 6c0f4f9374b..af7552f2e30 100644
--- a/studio/backend/tests/test_diffusion_routes.py
+++ b/studio/backend/tests/test_diffusion_routes.py
@@ -3407,3 +3407,40 @@ def test_connection_png_parameters_leave_out_unsent_settings():
assert text == "a sloth\nSize: 512x256, Model: qwen-image"
local = _params_text({"prompt": "a sloth", "steps": 9, "guidance": 0.0, "seed": 123})
assert "Steps: 9" in local and "Seed: 123" in local
+
+
+def test_a_retired_flux3_full_copy_reaches_the_backend_as_its_base(client):
+ # unsloth/flux-3-image-klein is a retired full copy: the plan and the load both see the base it copies, which the
+ # real backend fetches through unsloth/flux-3-image-klein-FP8.
+ from core.inference.diffusion_families import detect_family
+
+ backend = diffusion_module.get_diffusion_backend()
+ seen: list[tuple] = []
+
+ def _validate(model_path, **kwargs):
+ seen.append(("validate", model_path, kwargs.get("gguf_filename"), kwargs.get("model_kind")))
+ return detect_family(model_path)
+
+ plan, load = backend.download_plan, backend.begin_load
+ backend.validate_load_request = _validate
+ backend.download_plan = lambda model_path, **kw: (
+ seen.append(("plan", model_path)),
+ plan(model_path, **kw),
+ )[1]
+ backend.begin_load = lambda model_path, **kw: (
+ seen.append(("load", model_path)),
+ load(model_path, **kw),
+ )[1]
+ body = {
+ "model_path": "unsloth/flux-3-image-klein",
+ "gguf_filename": "model.safetensors",
+ "model_kind": "single_file",
+ }
+ assert _post_download_plan(client, **body).status_code == 200
+ assert _post_load(client, **body).status_code == 200
+ bases = {entry[1] for entry in seen}
+ assert bases == {"black-forest-labs/flux-3-image-klein"}, seen
+ assert ("plan", "black-forest-labs/flux-3-image-klein") in seen
+ assert ("load", "black-forest-labs/flux-3-image-klein") in seen
+ validated = [entry[2:] for entry in seen if entry[0] == "validate"]
+ assert validated and set(validated) == {(None, "pipeline")}, seen
diff --git a/studio/backend/tests/test_flux3_retired_full_copies.py b/studio/backend/tests/test_flux3_retired_full_copies.py
new file mode 100644
index 00000000000..e1b294e41a5
--- /dev/null
+++ b/studio/backend/tests/test_flux3_retired_full_copies.py
@@ -0,0 +1,128 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""unsloth/flux-3-image-klein[-base] are retired full copies: a load naming one becomes the pick of the base it copies,
+which Studio fetches through the -FP8 repo."""
+
+import pytest
+
+from core.inference import diffusion_families as df
+from models.inference import DiffusionLoadRequest
+
+_COPIES = {
+ "unsloth/flux-3-image-klein": (
+ "black-forest-labs/flux-3-image-klein",
+ "unsloth/flux-3-image-klein-FP8",
+ ),
+ "unsloth/flux-3-image-klein-base": (
+ "black-forest-labs/flux-3-image-klein-base",
+ "unsloth/flux-3-image-klein-base-FP8",
+ ),
+}
+
+
[email protected]("copy", sorted(_COPIES))
+def test_each_retired_copy_points_at_a_mirrored_base_of_the_same_family(copy):
+ base, mirror = _COPIES[copy]
+ assert df.retired_full_copy_base(copy) == base
+ assert df.retired_full_copy_base(copy.upper()) == base
+ assert df.mirror_repo(base) == mirror
+ assert df.detect_family(base) is df.detect_family(copy)
+
+
[email protected]("copy", sorted(_COPIES))
+def test_a_pipeline_pick_of_a_retired_copy_loads_its_base(copy):
+ base, _mirror = _COPIES[copy]
+ request = DiffusionLoadRequest(model_path = copy, model_kind = "pipeline", base_repo = copy)
+ assert request.model_path == base
+ assert request.base_repo == base
+ assert request.model_kind == "pipeline"
+ assert DiffusionLoadRequest(model_path = f" {copy} ").model_path == base
+
+
+def test_a_single_file_pick_of_the_root_bf16_transformer_is_the_pipeline_load():
+ request = DiffusionLoadRequest(
+ model_path = "unsloth/flux-3-image-klein",
+ gguf_filename = "model.safetensors",
+ model_kind = "single_file",
+ )
+ assert (request.model_path, request.gguf_filename, request.model_kind) == (
+ "black-forest-labs/flux-3-image-klein",
+ None,
+ "pipeline",
+ )
+
+
+def test_a_downloaded_snapshot_of_a_retired_copy_loads_its_base():
+ # The Hub picker hands a cached repo over as its snapshot path, with the repo as the display id.
+ request = DiffusionLoadRequest(
+ model_path = "/hf/hub/models--unsloth--flux-3-image-klein-base/snapshots/abc",
+ display_repo_id = "unsloth/flux-3-image-klein-base",
+ )
+ assert request.model_path == "black-forest-labs/flux-3-image-klein-base"
+ assert request.display_repo_id is None
+
+
+def test_a_bare_snapshot_path_of_a_retired_copy_loads_its_base():
+ # An API caller (or a model remembered by an older build) names the cached snapshot alone.
+ for path in (
+ "/hf/hub/models--unsloth--flux-3-image-klein/snapshots/0123abc",
+ "C:\\Users\\me\\.cache\\huggingface\\hub\\models--unsloth--flux-3-image-klein\\snapshots\\0123abc\\",
+ ):
+ assert (
+ DiffusionLoadRequest(model_path = path).model_path
+ == "black-forest-labs/flux-3-image-klein"
+ )
+ # Another repo's snapshot, or the -FP8 mirror's, is a local load as before.
+ for path in (
+ "/hf/hub/models--unsloth--flux-3-image-klein-FP8/snapshots/0123abc",
+ "/hf/hub/models--unsloth--flux-3-image-klein/blobs/0123abc",
+ ):
+ assert DiffusionLoadRequest(model_path = path).model_path == path
+
+
+def test_other_picks_are_left_as_named():
+ # Anything that is not the base pipeline or its root transformer keeps naming the copy (it still exists).
+ kept = DiffusionLoadRequest(
+ model_path = "unsloth/flux-3-image-klein",
+ gguf_filename = "model.safetensors",
+ model_kind = "single_file",
+ vae_file = "unsloth/flux-3-image-klein-FP8/vae/diffusion_pytorch_model.safetensors",
+ )
+ assert kept.model_path == "unsloth/flux-3-image-klein"
+ assert kept.gguf_filename == "model.safetensors"
+ with_encoder = DiffusionLoadRequest(
+ model_path = "unsloth/flux-3-image-klein",
+ gguf_filename = "model.safetensors",
+ model_kind = "single_file",
+ text_encoder_file = "unsloth/flux-3-image-klein-FP8/flux-3-image-klein-text_encoder-FP8.safetensors",
+ )
+ assert with_encoder.model_path == "unsloth/flux-3-image-klein"
+ # Another companion base keeps the single-file build; the base it copies (or the copy itself) does not.
+ other_base = DiffusionLoadRequest(
+ model_path = "unsloth/flux-3-image-klein",
+ gguf_filename = "model.safetensors",
+ model_kind = "single_file",
+ base_repo = "/packs/my-flux3-base",
+ )
+ assert (other_base.model_path, other_base.gguf_filename) == (
+ "unsloth/flux-3-image-klein",
+ "model.safetensors",
+ )
+ for same in ("black-forest-labs/flux-3-image-klein", "unsloth/flux-3-image-klein"):
+ request = DiffusionLoadRequest(
+ model_path = "unsloth/flux-3-image-klein",
+ gguf_filename = "model.safetensors",
+ model_kind = "single_file",
+ base_repo = same,
+ )
+ assert (request.model_path, request.model_kind) == (
+ "black-forest-labs/flux-3-image-klein",
+ "pipeline",
+ )
+ for repo in (
+ "unsloth/flux-3-image-klein-FP8",
+ "black-forest-labs/flux-3-image-klein",
+ "unsloth/FLUX.1-dev",
+ ):
+ assert DiffusionLoadRequest(model_path = repo).model_path == repo
diff --git a/studio/backend/tests/test_media_auto_switch.py b/studio/backend/tests/test_media_auto_switch.py
index 0fb48574066..5a23f60d7a8 100644
--- a/studio/backend/tests/test_media_auto_switch.py
+++ b/studio/backend/tests/test_media_auto_switch.py
@@ -2785,3 +2785,59 @@ def test_a_media_request_parked_on_a_gate_is_not_read_as_running_chat_work(monke
tracker._inflight = tracker._pending = 0
assert [entry.model_id for entry in started] == ["org/target"]
+
+
+def test_a_downloaded_retired_flux3_copy_switches_to_the_base_it_copies(
+ catalog, enabled, backend, loads, tmp_path
+):
+ # unsloth/flux-3-image-klein is a retired full copy that the load route redirects to its BFL base (fetched from the
+ # -FP8 mirror). The switch has to prove THAT load is cached, and recognise the base it publishes as resident.
+ snapshot = tmp_path / "flux3-copy"
+ snapshot.mkdir()
+ (snapshot / "modular_model_index.json").write_text("{}")
+ catalog.append(_info("unsloth/flux-3-image-klein", snapshot, task = mas.IMAGE_TASK))
+ planned: list = []
+
+ def _plan(model_path, **kwargs):
+ planned.append(model_path)
+ return {"total_bytes": backend.missing_bytes}
+
+ backend.download_plan = _plan
+ base = "black-forest-labs/flux-3-image-klein"
+ backend.missing_bytes = 5_000
+ with pytest.raises(HTTPException) as excinfo:
+ _switch("unsloth/flux-3-image-klein")
+ assert excinfo.value.status_code == 409 and loads == []
+ assert planned and set(planned) == {base}
+
+ backend.missing_bytes = 0
+ _switch("unsloth/flux-3-image-klein")
+ assert [(p.model_id, p.model_path, p.model_kind) for _owner, p in loads] == [
+ (base, base, "pipeline")
+ ]
+ # Resident as the base: the same request is answered without another load.
+ _switch("unsloth/flux-3-image-klein")
+ assert len(loads) == 1
+
+
+def test_a_retired_flux3_copy_name_reloads_the_mirror_that_replaced_it(
+ catalog, enabled, backend, loads, tmp_path
+):
+ # Picking the retired copy now stages its base's -FP8 mirror, so a later API request still naming the copy must find
+ # that download rather than answer model_not_found.
+ snapshot = tmp_path / "flux3-fp8"
+ snapshot.mkdir()
+ (snapshot / "modular_model_index.json").write_text("{}")
+ catalog.append(_info("unsloth/flux-3-image-klein-FP8", snapshot, task = mas.IMAGE_TASK))
+ _switch("unsloth/flux-3-image-klein")
+ base = "black-forest-labs/flux-3-image-klein"
+ assert [(p.model_id, p.model_path, p.model_kind) for _owner, p in loads] == [
+ (base, base, "pipeline")
+ ]
+ # The base, resident (as the Images page loads it), answers the copy's name without a reload.
+ _switch("unsloth/flux-3-image-klein")
+ assert len(loads) == 1
+ # A name with no retired mapping still refuses.
+ with pytest.raises(HTTPException) as excinfo:
+ _switch("unsloth/not-a-model")
+ assert excinfo.value.status_code == 404
diff --git a/studio/frontend/src/features/images/image-model-recall.ts b/studio/frontend/src/features/images/image-model-recall.ts
index 06b006fc22e..be9ac95dcae 100644
--- a/studio/frontend/src/features/images/image-model-recall.ts
+++ b/studio/frontend/src/features/images/image-model-recall.ts
@@ -16,6 +16,50 @@ export interface RememberedImageModel {
const KEY = "unsloth:images:last-model";
+// Retired full copies of the gated FLUX.3 repos. They stay on the Hub for existing links, but Studio's copy of those
+// files lives in the -FP8 repos, so a pick naming one loads the base it copies (as the backend redirects it), and the
+// remembered model matches the status the load reports. The root model.safetensors is that base's bf16 transformer.
+const RETIRED_FULL_COPIES: Record<string, string> = {
+ "unsloth/flux-3-image-klein": "black-forest-labs/flux-3-image-klein",
+ "unsloth/flux-3-image-klein-base": "black-forest-labs/flux-3-image-klein-base",
+};
+
+// ``.../models--unsloth--flux-3-image-klein/snapshots/<sha>`` -> the repo id it is a snapshot of ("" otherwise).
+function retiredSnapshotRepo(path: string): string {
+ const match = /(?:^|[\\/])models--unsloth--(flux-3-image-klein(?:-base)?)[\\/]snapshots[\\/][^\\/]+[\\/]?$/i.exec(
+ path.trim(),
+ );
+ return match ? `unsloth/${match[1].toLowerCase()}` : "";
+}
+
+export function redirectRetiredImagePick<
+ T extends {
+ repoId: string;
+ kind: RememberedImageModel["kind"];
+ filename?: string;
+ displayRepoId?: string;
+ textEncoderFiles?: readonly string[];
+ vaeFile?: string;
+ },
+>(pick: T): T {
+ // A downloaded copy arrives as its snapshot path with the retired id as the display id; a model remembered by an
+ // older build is that snapshot path alone.
+ const base =
+ RETIRED_FULL_COPIES[pick.repoId.trim().toLowerCase()] ??
+ RETIRED_FULL_COPIES[(pick.displayRepoId ?? "").trim().toLowerCase()] ??
+ RETIRED_FULL_COPIES[retiredSnapshotRepo(pick.repoId)];
+ if (!base) return pick;
+ const { displayRepoId: _display, ...rest } = pick;
+ if (pick.kind === "pipeline") return { ...rest, repoId: base } as T;
+ // Supplied encoder / VAE files make it a different build, which the backend leaves on the copy too.
+ const components = (pick.textEncoderFiles?.length ?? 0) > 0 || Boolean(pick.vaeFile);
+ if (pick.kind === "single_file" && pick.filename === "model.safetensors" && !components) {
+ const { filename: _filename, textEncoderFiles: _te, vaeFile: _vae, ...model } = rest;
+ return { ...model, repoId: base, kind: "pipeline" } as T;
+ }
+ return pick;
+}
+
export function readImageModel(): RememberedImageModel | null {
try {
const value = JSON.parse(localStorage.getItem(KEY) ?? "null");
@@ -33,7 +77,7 @@ export function readImageModel(): RememberedImageModel | null {
(f: unknown): f is string => typeof f === "string" && f.length > 0,
)
: [];
- return {
+ return redirectRetiredImagePick({
repoId: value.repoId,
kind: value.kind,
...(typeof value.filename === "string"
@@ -44,7 +88,7 @@ export function readImageModel(): RememberedImageModel | null {
...(typeof value.vaeFile === "string" && value.vaeFile
? { vaeFile: value.vaeFile }
: {}),
- };
+ } as RememberedImageModel);
} catch {
return null;
}
diff --git a/studio/frontend/src/features/images/images-page.tsx b/studio/frontend/src/features/images/images-page.tsx
index 73c325806b9..a837d734aef 100644
--- a/studio/frontend/src/features/images/images-page.tsx
+++ b/studio/frontend/src/features/images/images-page.tsx
@@ -2,7 +2,7 @@
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
import { generationFailureLogsAction } from "@/features/settings/lib/view-logs-action";
-import { readImageModel, rememberImageModel, matchesRememberedModel, componentFilesMatch, type RememberedImageModel } from "./image-model-recall";
+import { readImageModel, redirectRetiredImagePick, rememberImageModel, matchesRememberedModel, componentFilesMatch, type RememberedImageModel } from "./image-model-recall";
import { componentFileFields, splitComponentFileList } from "./component-files";
import {
type DragEvent,
@@ -3300,6 +3300,16 @@ export function ImagesPage({
// Whether THIS load carries the selection into the build, so a quantized load that did not can drop it.
bakedLorasOnLoad.current = bakeLoras.length > 0;
const componentFiles = componentFileFields(opts.kind, advanced.text_encoder_file, advanced.vae_file);
+ // A retired FLUX.3 full copy (named, or a downloaded snapshot of one) loads the base it copies, as the backend
+ // redirects it, so the load, Reapply and the remembered model all name the id the status will report.
+ const redirected = redirectRetiredImagePick({
+ repoId,
+ ...opts,
+ textEncoderFiles: componentFiles.text_encoder_file,
+ vaeFile: componentFiles.vae_file,
+ });
+ repoId = redirected.repoId;
+ opts = { kind: redirected.kind, filename: redirected.filename, displayRepoId: redirected.displayRepoId };
lastLoad.current = {
repoId,
kind: opts.kind,
@@ -3672,7 +3682,23 @@ export function ImagesPage({
if (!owns()) return true;
}
// ONE snapshot for the plan and the load it fires: the download runs for minutes without setting `busy`.
- const advanced = downloadSnapshot ?? currentLoadAdvanced(repoId, familyOverrideRequired);
+ let advanced = downloadSnapshot ?? currentLoadAdvanced(repoId, familyOverrideRequired);
+ // A retired FLUX.3 full copy is planned, staged and loaded as the base it copies, so the staged
+ // checkpoint is the one the load opens (the backend redirects the same picks).
+ const component = componentFileFields(opts.kind, advanced.text_encoder_file, advanced.vae_file);
+ const redirected = redirectRetiredImagePick({
+ repoId,
+ ...opts,
+ textEncoderFiles: component.text_encoder_file,
+ vaeFile: component.vae_file,
+ });
+ if (redirected.repoId !== repoId) {
+ repoId = redirected.repoId;
+ opts = { kind: redirected.kind, filename: redirected.filename, displayRepoId: redirected.displayRepoId };
+ advanced = downloadSnapshot ?? currentLoadAdvanced(repoId, familyOverrideRequired);
+ // A local snapshot of the copy is now a Hub load of the base: plan and stage it like one.
+ source = "hub";
+ }
if (source !== "hub" && !downloadOnly) return handleLoadRef.current(repoId, opts, advanced);
// Show feedback before the potentially slow Hub metadata request.
const pickToastId = downloadOnly ? undefined : pickToast.show();
diff --git a/studio/frontend/tests/image-retired-full-copies.test.ts b/studio/frontend/tests/image-retired-full-copies.test.ts
new file mode 100644
index 00000000000..645b0375f94
--- /dev/null
+++ b/studio/frontend/tests/image-retired-full-copies.test.ts
@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+ matchesRememberedModel,
+ readImageModel,
+ redirectRetiredImagePick,
+ rememberImageModel,
+} from "../src/features/images/image-model-recall.ts";
+import { installLocalStorageFake } from "./helpers/kit.ts";
+
+installLocalStorageFake();
+
+test("a pipeline pick of a retired FLUX.3 full copy loads the base it copies", () => {
+ assert.deepEqual(redirectRetiredImagePick({ repoId: "unsloth/flux-3-image-klein", kind: "pipeline" }), {
+ repoId: "black-forest-labs/flux-3-image-klein",
+ kind: "pipeline",
+ });
+ assert.equal(
+ redirectRetiredImagePick({ repoId: "Unsloth/FLUX-3-Image-Klein-Base", kind: "pipeline" as const }).repoId,
+ "black-forest-labs/flux-3-image-klein-base",
+ );
+});
+
+test("its root bf16 transformer is the pipeline load; other picks stay as named", () => {
+ assert.deepEqual(
+ redirectRetiredImagePick({
+ repoId: "unsloth/flux-3-image-klein",
+ kind: "single_file" as const,
+ filename: "model.safetensors",
+ }),
+ { repoId: "black-forest-labs/flux-3-image-klein", kind: "pipeline" },
+ );
+ // Supplied encoder / VAE files make it another build, which stays on the copy (the backend does the same).
+ const withVae = {
+ repoId: "unsloth/flux-3-image-klein",
+ kind: "single_file" as const,
+ filename: "model.safetensors",
+ vaeFile: "x/vae.safetensors",
+ };
+ assert.equal(redirectRetiredImagePick(withVae), withVae);
+ const withEncoder = { ...withVae, vaeFile: undefined, textEncoderFiles: ["x/te.safetensors"] };
+ assert.equal(redirectRetiredImagePick(withEncoder), withEncoder);
+ const other = { repoId: "unsloth/flux-3-image-klein-FP8", kind: "pipeline" as const };
+ assert.equal(redirectRetiredImagePick(other), other);
+});
+
+test("a downloaded snapshot of a retired copy is redirected by its display id", () => {
+ assert.deepEqual(
+ redirectRetiredImagePick({
+ repoId: "/hf/hub/models--unsloth--flux-3-image-klein-base/snapshots/abc",
+ kind: "pipeline" as const,
+ displayRepoId: "unsloth/flux-3-image-klein-base",
+ }),
+ { repoId: "black-forest-labs/flux-3-image-klein-base", kind: "pipeline" },
+ );
+});
+
+test("a remembered retired copy is recalled as its base, so it matches the status the load reports", () => {
+ rememberImageModel({ repoId: "unsloth/flux-3-image-klein", kind: "pipeline" });
+ const recalled = readImageModel();
+ assert.deepEqual(recalled, { repoId: "black-forest-labs/flux-3-image-klein", kind: "pipeline" });
+ assert.equal(
+ matchesRememberedModel(recalled!, {
+ loaded: true,
+ repo_id: "black-forest-labs/flux-3-image-klein",
+ model_kind: "pipeline",
+ }),
+ true,
+ );
+});
+
+test("a model remembered by an older build as the copy's snapshot path is recalled as its base", () => {
+ rememberImageModel({
+ repoId: "/home/me/.cache/huggingface/hub/models--unsloth--flux-3-image-klein/snapshots/0123abc",
+ kind: "pipeline",
+ });
+ assert.deepEqual(readImageModel(), { repoId: "black-forest-labs/flux-3-image-klein", kind: "pipeline" });
+ const mirror = {
+ repoId: "/home/me/.cache/huggingface/hub/models--unsloth--flux-3-image-klein-FP8/snapshots/0123abc",
+ kind: "pipeline" as const,
+ };
+ assert.equal(redirectRetiredImagePick(mirror), mirror);
+});