unslothai/unsloth · warning · ValueError

save_directory path components must be <= 255 characters

Error message

save_directory path components must be <= 255 characters

What it means

ValueError from _validate_save_directory when any single path component exceeds 255 characters. The limit is checked across POSIX parts, Windows (PureWindowsPath) parts, and naive backslash-split parts, so it catches oversized components regardless of which OS will consume the path — most filesystems (ext4, NTFS, APFS names) cap individual name components near 255 bytes.

Source

Thrown at studio/backend/models/export.py:26

from pydantic import BaseModel, Field, field_validator
from typing import List, Optional, Literal, Dict, Any, Union


def _validate_save_directory(value: str) -> str:
    """Validate save_directory — allows absolute paths (user may want a different drive)."""
    if value is None:
        raise ValueError("save_directory is required")
    raw = str(value).strip()
    if not raw:
        raise ValueError("save_directory must not be empty")
    if "\x00" in raw:
        raise ValueError("save_directory may not contain null bytes")
    if any(ch in raw for ch in ("\r", "\n")):
        raise ValueError("save_directory may not contain control characters")
    path = Path(raw).expanduser()
    path_parts = (*path.parts, *PureWindowsPath(raw).parts, *raw.replace("\\", "/").split("/"))
    if any(len(part) > 255 for part in path_parts if part not in ("", ".", "/", "\\")):
        raise ValueError("save_directory path components must be <= 255 characters")
    if (
        ".." in path.parts
        or ".." in PureWindowsPath(raw).parts
        or ".." in raw.replace("\\", "/").split("/")
    ):
        raise ValueError("save_directory may not contain '..' segments")
    return raw


class LoadCheckpointRequest(BaseModel):
    """Request for loading a checkpoint into the export backend."""

    checkpoint_path: str = Field(..., description = "Path to the checkpoint directory")
    max_seq_length: int = Field(
        2048,
        ge = 128,
        le = 32768,
        description = "Maximum sequence length for loading the model",

View on GitHub (pinned to 203007d190)

Solutions

1. Shorten the offending component (usually the auto-generated leaf directory name) to under 255 characters.
2. Split long names across nested subdirectories instead of one giant component.
3. Truncate generated names client-side with a sane cap (e.g. 100 chars) plus a short hash suffix for uniqueness.

Example fix

# before
save_directory = f"/exports/{model_name}-{full_config_json}"  # one huge component
# after
save_directory = f"/exports/{model_name[:80]}-{hashlib.sha1(cfg).hexdigest()[:8]}"

def save_directory_components_short(payload: dict, limit: int = 255) -> bool:
    v = payload.get("save_directory")
    if not isinstance(v, str):
        return False
    parts = v.replace("\\", "/").split("/")
    return all(len(p) <= limit for p in parts if p not in ("", "."))

def is_short_component_path(v: str, limit: int = 255) -> bool:
    return all(
        len(p) <= limit
        for p in v.replace("\\", "/").split("/")
        if p not in ("", ".")
    )

When it happens

Trigger: Sending a save_directory where one directory or file name component is longer than 255 chars — e.g. a model name + suffix + timestamp concatenated into one directory name, or Windows-style 'C:\<very long segment>\out' where the long segment exceeds the cap.

Common situations: Auto-generated export dir names built from long model identifiers or full prompt strings; Windows long-path issues; clients that never truncate user-provided names.

Related errors

• save_directory is required
• save_directory must not be empty
• save_directory may not contain null bytes
• save_directory may not contain control characters
• save_directory may not contain '..' segments

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