unslothai/unsloth · error · ValueError

Unsupported transformer_cache '{value}'. Use one of: off, au

Error message

Unsupported transformer_cache '{value}'. Use one of: off, auto, {', '.join(TC_MODES)}.

What it means

normalize_transformer_cache() normalises the transformer_cache setting (lowercase, strip, hyphens to underscores) and accepts: None/''/'none'/'off' -> disabled, 'auto' -> loader decides from step count, or one of TC_MODES (currently just 'fbcache', first-block cache). Anything else raises ValueError so a typo'd mode fails at request time, not silently mid-generation.

Source

Thrown at studio/backend/core/inference/diffusion_cache.py:49

DEFAULT_FBCACHE_THRESHOLD = 0.08
QUANT_FBCACHE_THRESHOLD = 0.12

# Auto step-count bar: FBCache's win scales with step count, so auto engages only at 20+ steps ("dev" schedules qualify, distilled turbo never does).
FBCACHE_MIN_STEPS = 20


def normalize_transformer_cache(value: Optional[str]) -> Optional[str]:
    """Lower/strip a cache mode; None / "" / "none" / "off" -> None, "auto" -> TC_AUTO (loader
    decides from step count). Raises ValueError for an unsupported value."""
    if value is None:
        return None
    normalized = str(value).strip().lower().replace("-", "_")
    if not normalized or normalized in ("none", "off"):
        return None
    if normalized == TC_AUTO:
        return TC_AUTO
    if normalized not in TC_MODES:
        raise ValueError(
            f"Unsupported transformer_cache '{value}'. Use one of: off, auto, "
            f"{', '.join(TC_MODES)}."
        )
    return normalized


def _invalidate_child_registry_cache(transformer: Any) -> None:
    """Drop the HookRegistry's cached child-registry list after (un)installing hooks.

    ``cache_context`` propagates state through ``_get_child_registries``, which diffusers 0.39
    caches on first use. An uncached generation already calls it, creating an EMPTY cached child
    list -- so a later ``enable_cache`` installs block hooks ``_set_context`` never reaches and the
    first cached forward dies with "No context is set". Invalidate so the next ``cache_context``
    rebuilds it over the freshly hooked blocks. Best-effort."""
    registry = getattr(transformer, "_diffusers_hook", None)
    if registry is not None and getattr(registry, "_child_registries_cache", None) is not None:
        try:
            registry._child_registries_cache = None

View on GitHub (pinned to 203007d190)

Solutions

Use one of: 'off' (or 'none'/null/''), 'auto', or 'fbcache'.
Hyphenated 'fb-cache' also works since '-' is normalised to '_'.
Omit the setting entirely to keep the default (disabled).

Example fix

# before
engine.load(repo, transformer_cache="first_block_cache")
# after
engine.load(repo, transformer_cache="fbcache")  # or "auto"

Defensive patterns

Strategy: validation

Validate before calling

TC_VALID = {"off", "none", "auto", "fbcache"}

def valid_transformer_cache(v) -> bool:
    return v is None or str(v).strip().lower().replace("-", "_") in TC_VALID

Type guard

def is_valid_cache_mode(v) -> bool:
    return v is None or str(v).strip().lower().replace("-", "_") in {"off", "none", "auto", "fbcache"}

Try / catch

try:
    engine.load(repo, transformer_cache=mode)
except ValueError as e:
    if "Unsupported transformer_cache" in str(e):
        engine.load(repo, transformer_cache="auto")
    else:
        raise

Prevention

Limit the config enum to off/auto/fbcache (fb-cache also normalises).
Omit the setting when caching is not intentional — the default is disabled.

When it happens

Trigger: Passing transformer_cache='fbcach', 'fb_cache', 'first-block', 'full', or any string not in {off, none, auto, fbcache}. Note 'fb-cache' is fine (hyphen normalised) but other spellings are not aliases.

Common situations: Guessing cache mode names from docs or other engines; renaming drift across versions; config files copied between projects with different accepted vocabularies.

Related errors

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