unslothai/unsloth · error · Exception

{error_msg} (dynamic, from format_error_message: e.g. "Model

Error message

{error_msg} (dynamic, from format_error_message: e.g. "Model '{model_short}' not found. Check the model name.", "Not enough {device_label} memory to load '{model_short}'. Try a smaller model or free memory.", or str(error))

What it means

The inference engine's model-load path wraps any exception during load_model and re-raises it as a generic Exception whose message comes from format_error_message(e, config.identifier). That helper maps common failures to friendly text — 'Model X not found. Check the model name.', 'Not enough {device} memory to load X...' — and falls back to str(error) otherwise. Because it raises bare Exception (not a specific type), callers cannot catch selectively by type.

Source

Thrown at studio/backend/core/inference/inference.py:698

            self._load_chat_template_info(model_name)

            self.active_model_name = model_name
            self.loading_models.discard(model_name)

            logger.info(f"Successfully loaded model: {model_name}")
            log_gpu_memory(f"After loading {model_name}")
            return True

        except Exception as e:
            logger.error(f"Failed to load model: {e}")
            error_msg = format_error_message(e, config.identifier)

            # Cleanup on failure
            if model_name in self.models:
                del self.models[model_name]
            self.loading_models.discard(model_name)

            raise Exception(error_msg)

    def unload_model(self, model_name: str) -> bool:
        """Remove a model from the registry and clear GPU memory."""
        if model_name in self.models:
            try:
                # Clean up codecs for audio models
                if self.models[model_name].get("is_audio"):
                    self._audio_codec_manager.unload()

                logger.info(f"Unloading model '{model_name}' from memory.")
                del self.models[model_name]

                # Clear the active model if it was the one unloaded
                if self.active_model_name == model_name:
                    self.active_model_name = None

                clear_gpu_cache()

View on GitHub (pinned to 203007d190)

Solutions

Match the message: 'not found' → fix the model id; 'Not enough memory' → pick a smaller model/quantization or free VRAM
For other messages, the raw str(error) is included — act on that underlying text
Free GPU memory (unload other models) or upgrade hardware/quantization
Verify the model snapshot is complete (re-download if the cache is corrupt)

Defensive patterns

Strategy: try-catch

Validate before calling

# Validate before loading
from huggingface_hub import model_info

def model_exists(model_id: str) -> bool:
    try:
        model_info(model_id)
        return True
    except Exception:
        return False

Try / catch

try:
    engine.load_model(name)
except Exception as e:
    msg = str(e)
    if "not found" in msg:
        surface("unknown model", 404)
    elif "Not enough" in msg and "memory" in msg:
        surface("insufficient memory — try a smaller model", 507)
    else:
        surface(msg, 500)

Prevention

Because it raises bare Exception, catch broadly and branch on message text
Free VRAM (unload unused models) before loading new ones
Pre-verify model ids exist and the cache snapshot is complete

When it happens

Trigger: load_model failing on: a nonexistent or mistyped model id, insufficient GPU/VRAM (or unified memory) for the weights, missing files on disk, architecture incompatibility, or dependency errors — anything in the load path including transformers/from_pretrained failures.

Common situations: Model id typos; picking a model too large for the GPU; interrupted downloads leaving corrupt snapshots; mismatched transformers version for the model architecture; GGUF/diffusers dependency missing.

Related errors

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