unslothai/unsloth · error · ValueError

subset contains invalid characters

Error message

subset contains invalid characters

What it means

Raised by the _check_subset field validator: after the length cap, the subset must satisfy valid_hf_dataset_config_name(), the Hugging Face config-name charset rules. This rejects spaces, slashes, colons, and other characters that are not legal in an HF dataset config name. It is the subset analogue of the per-segment regex applied to hf_dataset.

Source

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

            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",
        "dataset_local_path",
        "model_snapshot_path",
        "dataset_snapshot_path",
    )
    @classmethod
    def _check_cache_local_path(cls, v: Optional[str]) -> Optional[str]:
        if v is None:
            return v
        v = v.strip()
        if not v:
            return None
        if len(v) > 4096:
            raise ValueError("local cache path is too long (max 4096 chars)")
        if "\x00" in v:

View on GitHub (pinned to 203007d190)

Solutions

1. Use a plain config name matching HF rules (typically letters, digits, dash, underscore, dot), e.g. 'plain_text'.
2. List the dataset's real configs via the HF API and present them as a dropdown instead of free text.
3. Slugify user input client-side before sending.

Example fix

// before
{ subset: "My Config (v2)" }
// after
{ subset: "my-config-v2" }

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

def subset_chars_valid(body: dict) -> bool:
    v = (body.get("subset") or "").strip()
    return v == "" or bool(_CONFIG_NAME.fullmatch(v))

const CONFIG_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
function subsetCharsOk(subset: string | undefined): boolean {
  const v = subset?.trim() ?? '';
  return v === '' || CONFIG_NAME.test(v);
}

When it happens

Trigger: POST a training start request with a subset containing invalid characters, e.g. 'my subset', 'config/v2', 'train:latest', or a URL fragment.

Common situations: Free-text UI input without charset validation; deriving subset from filenames with spaces; copying values from YAML keys that contain colons.

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 contains invalid characters or path segments
• subset is too long (max {MAX_HF_DATASET_OPTION_LENGTH} chars
• hf_dataset is too long (max 256 chars)
• split name is too long (max {MAX_HF_DATASET_OPTION_LENGTH} c
• s3_config requires either use_iam_role=True or both access_k

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