unslothai/unsloth · error · ValueError

'{base_model}' ships LTX-2.3 as single-file checkpoints with

Error message

'{base_model}' ships LTX-2.3 as single-file checkpoints with no diffusers layout, so it cannot be a training base yet: the trainer loads a base with from_pretrained, while 2.3 has to be assembled with from_single_file plus components from the 2.0 base. Train from 'Lightricks/LTX-2' instead.

What it means

LTX-2.3 checkpoints ship as single files with no diffusers layout (no model_index.json, no transformer/ or scheduler/ subfolders). Inference assembles them with from_single_file plus 2.0-base components, but the trainer only knows pipeline.from_pretrained. The family router still resolves 'lightricks/ltx-2.3' to family ltx-2, so without this explicit refusal the run would pass preflight, evict the user's resident models, and only fail in the spawned child.

Source

Thrown at studio/backend/core/training/diffusion_train_common.py:1780

        # MiniMax-H3's official base, for the same reason: safetensors-only, no remote code.
        "minimaxai/minimax-h3",
    }
)

# LTX-2.3 repos hold SINGLE-FILE checkpoints (ltx-2.3-22b-*.safetensors) and no diffusers layout:
# no model_index.json, no transformer/ or scheduler/ subfolder. Inference assembles them with
# from_single_file plus 2.3 config overrides and components borrowed from the 2.0 base (see
# core/inference/video_ltx2.py); the trainer only knows LTX2Pipeline.from_pretrained, which cannot
# read that layout. The name still resolves to the ``ltx-2`` family, so without an explicit refusal
# the run passes preflight, evicts the user's resident models, and only then fails in the child.
_LTX23_TRAIN_UNSUPPORTED = ("lightricks/ltx-2.3", "lightricks/ltx-2.3-fp8")


def _refuse_ltx23_training_base(base_model: str) -> None:
    """Raise for an LTX-2.3 base: the family routing accepts it, the training loader cannot."""
    if str(base_model or "").strip().lower() not in _LTX23_TRAIN_UNSUPPORTED:
        return
    raise ValueError(
        f"'{base_model}' ships LTX-2.3 as single-file checkpoints with no diffusers layout, so it "
        f"cannot be a training base yet: the trainer loads a base with from_pretrained, while 2.3 "
        f"has to be assembled with from_single_file plus components from the 2.0 base. Train from "
        f"'Lightricks/LTX-2' instead."
    )


def _assert_trusted_base_model(base_model: str, *, allow_modular: bool = False) -> None:
    """Gate the training base model the same way the inference backend gates non-GGUF loads:
    a local path or a trusted repo (``unsloth/*`` or an allowlisted official base). This runs
    BEFORE ``from_pretrained`` so an untrusted remote repo (which could ship pickle weights)
    is never fetched or deserialised.

    ``allow_modular`` is for a trainer whose loader is ``ModularPipeline.from_pretrained``: a
    local MiniMax-H3 pipeline carries ``modular_model_index.json`` and no ``model_index.json``,
    so the conventional shape check rejected the one local layout that family HAS."""
    from core.inference.diffusion import _assert_local_base_is_pipeline, _is_trusted_diffusion_repo

View on GitHub (pinned to 203007d190)

Solutions

Train from 'Lightricks/LTX-2' (the 2.0 diffusers-layout base) instead.
If you specifically need 2.3 weights, wait for trainer support or export/assemble a diffusers-layout repo from the 2.0 base — do not point the trainer at the single-file checkpoint.

Example fix

# before
cfg = DiffusionLoraConfig(base_model='Lightricks/LTX-2.3')
# after
cfg = DiffusionLoraConfig(base_model='Lightricks/LTX-2')

Defensive patterns

Strategy: validation

Validate before calling

_LTX23 = ('lightricks/ltx-2.3', 'lightricks/ltx-2.3-fp8')
if str(base_model or '').strip().lower() in _LTX23:
    raise ValueError('LTX-2.3 cannot be a training base; use Lightricks/LTX-2')

Prevention

Filter base-model pickers by 'trainable: true' so inference-only repos never reach the trainer.
When a family adds a new checkpoint format, check whether the training loader supports it before advertising it.

When it happens

Trigger: Starting training with base_model='Lightricks/LTX-2.3' or 'Lightricks/LTX-2.3-fp8' (case-insensitive, whitespace-tolerant).

Common situations: User picks the newest LTX checkpoint seen working in inference and assumes it is trainable; UI family dropdown lists 2.3 repos without distinguishing trainability.

Related errors

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/bb440465cf5a8029. Report an issue: GitHub.