unslothai/unsloth · warning · ValueError

save_directory is required

Error message

save_directory is required

What it means

ValueError from _validate_save_directory when the Export API request's save_directory field is None. The validator is the shared field_validator for all export request models; it fails fast on a missing destination before any filesystem work starts.

Source

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

# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""Pydantic schemas for Export API."""

from pathlib import Path, PureWindowsPath

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

View on GitHub (pinned to 203007d190)

Solutions

1. Always include 'save_directory' as a string in export request payloads.
2. If the destination is user-chosen, default it in the client (e.g. last-used export dir) rather than sending null.
3. Treat the 422 detail message as the cue that the key is missing, not malformed.

Example fix

// before
{ "format": "gguf" }
// after
{ "format": "gguf", "save_directory": "/exports/model" }

def save_directory_present(payload: dict) -> bool:
    return isinstance(payload.get("save_directory"), str)

def has_save_directory(p: dict) -> bool:
    return isinstance(p.get("save_directory"), str)

When it happens

Trigger: POSTing an export request whose JSON omits 'save_directory' entirely or explicitly sets it to null, unless the model declares a default (some models mark it required, in which case Pydantic's own 'Field required' error fires first).

Common situations: Optional-field handling in clients that send null for unset values; schema drift where an older client omitted the field; copy/paste payloads missing the destination.

Related errors

• save_directory must not be empty
• save_directory path components must be <= 255 characters
• Invalid version.
• Provide either content_base64 or file_ids, not both
• Provide either content_base64 or file_ids

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