unslothai/unsloth · error · ValueError

Unsupported diffusion memory_mode '{value}'. Use one of: {va

Error message

Unsupported diffusion memory_mode '{value}'. Use one of: {valid}.

What it means

normalize_memory_mode validates the user-supplied memory_mode parameter for diffusion loads before any GPU work happens. It lowercases, strips, and converts dashes to underscores, then requires membership in MEMORY_MODES ('auto', 'fast', 'balanced', 'low_vram'). An unknown value raises ValueError so the HTTP route rejects it as 4xx cheaply.

Source

Thrown at studio/backend/core/inference/diffusion_memory.py:66

DEFAULT_GROUP_BLOCKS = 1

DEFAULT_IMAGE_WIDTH = 1024
DEFAULT_IMAGE_HEIGHT = 1024
# Flat allowance for fixed pipeline costs (scheduler, embeddings, CUDA context, fragmentation).
DEFAULT_BASE_OVERHEAD_MIB = 2048


def normalize_memory_mode(value: Optional[str]) -> Optional[str]:
    """Lower/strip a requested mode (accepting dashes); None passes through. Raises ValueError
    for an unsupported mode so the route rejects it as a 4xx before any GPU work."""
    if value is None:
        return None
    normalized = str(value).strip().lower().replace("-", "_")
    if not normalized:
        return None
    if normalized not in MEMORY_MODES:
        valid = ", ".join(MEMORY_MODES)
        raise ValueError(f"Unsupported diffusion memory_mode '{value}'. Use one of: {valid}.")
    return normalized


@dataclass(frozen = True)
class DeviceMemory:
    """Point-in-time view of the active device's memory, in MiB.

    ``memory_kind`` distinguishes discrete VRAM (CPU offload helps) from unified / system memory
    (offload moves bytes within the same pool, so it does not)."""

    backend: str
    device: str
    memory_kind: str  # "discrete_vram" | "unified_memory" | "system_memory" | "unknown"
    free_mib: Optional[int] = None
    total_mib: Optional[int] = None

    @property
    def is_unified(self) -> bool:

View on GitHub (pinned to 203007d190)

Solutions

Send one of: auto, fast, balanced, low_vram (dashes like 'low-vram' are accepted)
Omit memory_mode entirely to take the default (auto)
Update the client to the mode vocabulary of the deployed backend version

Example fix

// before
{"memory_mode": "lowvram"}
// after
{"memory_mode": "low_vram"}

Defensive patterns

Strategy: validation

Validate before calling

MODES = {"auto", "fast", "balanced", "low_vram"}

def valid_memory_mode(v: str | None) -> bool:
    if v is None:
        return True
    n = v.strip().lower().replace("-", "_")
    return n == "" or n in MODES

Type guard

def is_memory_mode(v) -> bool:
    return v is None or (isinstance(v, str) and (v.strip().lower().replace("-", "_") in {"", "auto", "fast", "balanced", "low_vram"}))

Try / catch

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

Prevention

Validate enum-ish params client-side against the documented mode list
Send snake_case values; the API tolerates dashes but not new names
Version-pin the client and backend vocabulary together

When it happens

Trigger: POSTing a diffusion load/generate request with memory_mode like 'lowvram', 'LOW-VRAM', 'medium', or 'high' — anything not normalizing to auto/fast/balanced/low_vram.

Common situations: Clients forwarding UI strings that don't match the API vocabulary; version drift where older/newer clients send a mode name this build doesn't know; typo'd config files.

Related errors

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