unslothai/unsloth · error · ValueError

Unsupported text_encoder_quant '{value}'. Use one of: {', '.

Error message

Unsupported text_encoder_quant '{value}'. Use one of: {', '.join(TE_QUANT_MODES)}.

What it means

normalize_text_encoder_quant validates the text_encoder_quant request parameter: lowercase/strip/dash-to-underscore, 'none'/'off'/'auto' and empty collapse to None, otherwise the value must be in TE_QUANT_MODES (fp8, nvfp4, int8, fp8_dynamic). Unknown values raise ValueError for cheap 4xx rejection. Note MiniMax-H3 reads the raw tri-state before normalization, so 'none' is meaningful there.

Source

Thrown at studio/backend/core/inference/diffusion_precision.py:78


def normalize_te_quant(value: Optional[str]) -> Optional[str]:
    """Lower/strip a requested text-encoder quant; None / "" / "none" / "off" / "auto" -> None.

    The three no-scheme spellings collapse here because no family quantises its encoder without
    a named scheme. They stay distinct to the caller that cares: MiniMax-H3 reads the RAW request
    as a tri-state (unset picks the hosted conditioner, "none"/"off" pin the released bf16 one)
    BEFORE normalising, so folding them is what lets an opt-out reach that branch at all instead
    of being rejected here.

    Raises ValueError for an unsupported value so a bad request is rejected cheaply."""
    if value is None:
        return None
    normalized = str(value).strip().lower().replace("-", "_")
    if not normalized or normalized in ("none", "off", "auto"):
        return None
    if normalized not in TE_QUANT_MODES:
        raise ValueError(
            f"Unsupported text_encoder_quant '{value}'. Use one of: {', '.join(TE_QUANT_MODES)}."
        )
    return normalized


def effective_te_quant(mode: Optional[str], family: Optional[str]) -> Optional[str]:
    """The text-encoder mode ``quantize_text_encoders`` will ACTUALLY attempt for ``family``.

    An explicit int8 on a family with no keep-bf16 schedule is rewritten to layerwise fp8
    before support is ever consulted -- a documented downgrade that reports ``fell_back`` and
    needs no torchao. A caller that asks ``te_quant_supported`` about the raw request therefore
    refuses loads the runtime would run: on Windows ROCm the torchao stub makes int8
    unsupported while fp8 still works.
    """
    normalized = normalize_te_quant(mode)
    if normalized == TE_QUANT_INT8 and _TE_INT8_SKIP.get((family or "").lower()) is None:
        return TE_QUANT_FP8
    return normalized

View on GitHub (pinned to 203007d190)

Solutions

Use one of: fp8, nvfp4, int8, fp8_dynamic (dashes accepted)
Send 'none', 'off', or omit the field to disable text-encoder quantization
Send 'auto' to take the family default

Example fix

// before
{"text_encoder_quant": "q8_0"}
// after
{"text_encoder_quant": "int8"}

Defensive patterns

Strategy: validation

Validate before calling

TE_MODES = {"fp8", "nvfp4", "int8", "fp8_dynamic"}

def valid_te_quant(v) -> bool:
    if v is None:
        return True
    n = str(v).strip().lower().replace("-", "_")
    return n in ("", "none", "off", "auto") | TE_MODES

Type guard

def is_te_quant(v) -> bool:
    return v is None or (isinstance(v, str) and str(v).strip().lower().replace("-", "_") in {"", "none", "off", "auto", "fp8", "nvfp4", "int8", "fp8_dynamic"})

Try / catch

try:
    normalize_text_encoder_quant(req.text_encoder_quant)
except ValueError as e:
    return JSONResponse(status_code=400, content={"detail": str(e)})

Prevention

Use the documented mode names; don't reuse llama.cpp quant suffixes
Remember 'none'/'off' are meaningful (disable), not invalid
Validate request enums at the client boundary

When it happens

Trigger: Request with text_encoder_quant set to something like 'q8', 'int4', 'bf16', or 'fp8-dynamic-tokens' — anything not in {fp8, nvfp4, int8, fp8_dynamic} after normalization.

Common situations: Clients guessing quant names from other ecosystems (llama.cpp suffixes, vLLM schemes); stale client sending a mode removed in this build; copy-paste from docs of a different product.

Related errors

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