unslothai/unsloth · error · ValueError

hf_dataset contains invalid characters or path segments

Error message

hf_dataset contains invalid characters or path segments

What it means

Raised by the _check_hf_dataset field validator: the dataset id is split on '/' and every segment must fullmatch the _HF_DATASET_ID_SEGMENT_RE pattern (Hugging Face id character rules). This catches invalid characters, empty segments from leading/trailing/double slashes, and malformed segments, after the length and '..' checks. The regex runs per-segment, so 'user//data' fails on the empty middle segment.

Source

Thrown at studio/backend/models/training.py:237

            raise ValueError(
                "dataset_slice_end must be greater than or equal to dataset_slice_start"
            )
        return self

    @field_validator("hf_dataset")
    @classmethod
    def _check_hf_dataset(cls, v: Optional[str]) -> Optional[str]:
        if v is None:
            return v
        v = v.strip()
        if not v:
            return None
        if len(v) > 256:
            raise ValueError("hf_dataset is too long (max 256 chars)")
        if ".." in v:
            raise ValueError("hf_dataset must not contain '..'")
        if any(_HF_DATASET_ID_SEGMENT_RE.fullmatch(segment) is None for segment in v.split("/")):
            raise ValueError("hf_dataset contains invalid characters or path segments")
        return v

    @field_validator("subset")
    @classmethod
    def _check_subset(cls, v: Optional[str]) -> Optional[str]:
        if v is None:
            return v
        v = v.strip()
        if not v:
            return None
        if len(v) > MAX_HF_DATASET_OPTION_LENGTH:
            raise ValueError(f"subset is too long (max {MAX_HF_DATASET_OPTION_LENGTH} chars)")
        if not valid_hf_dataset_config_name(v):
            raise ValueError("subset contains invalid characters")
        return v

    @field_validator(
        "model_local_path",

View on GitHub (pinned to 203007d190)

Solutions

1. Send a clean 'owner/dataset' (or single 'dataset') id with only valid HF id characters per segment.
2. Normalize client-side: strip, collapse duplicate slashes, drop leading/trailing slashes, then validate each segment against the same rules.
3. If the id came from a URL, parse it properly instead of string-replacing prefixes.

Example fix

// before
{ hf_dataset: "/user/data/" }
// after
{ hf_dataset: "user/data" }

import re
_HF_SEGMENT = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")

def dataset_segments_valid(body: dict) -> bool:
    v = (body.get("hf_dataset") or "").strip()
    return v != "" and all(_HF_SEGMENT.fullmatch(seg) for seg in v.split("/"))

const HF_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
function segmentsValid(id: string): boolean {
  return id.trim().split('/').every(s => HF_SEGMENT.test(s));
}

When it happens

Trigger: POST a training start request with hf_dataset like 'user//data' (double slash), '/user/data' (leading slash), 'user/data/' (trailing slash — though trailing whitespace is stripped first), or segments containing spaces, colons, or other characters outside the HF id charset.

Common situations: Programmatic string concatenation with an unexpected slash; URLs pasted and only partially cleaned; ids built from user handles containing whitespace or unicode; copy-paste artifacts like non-breaking spaces.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• hf_dataset is too long (max 256 chars)
• subset is too long (max {MAX_HF_DATASET_OPTION_LENGTH} chars
• subset contains invalid characters
• dataset_slice_end must be greater than or equal to dataset_s
• split name is too long (max {MAX_HF_DATASET_OPTION_LENGTH} c

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