unslothai/unsloth · error · ValueError

split name is too long (max {MAX_HF_DATASET_OPTION_LENGTH} c

Error message

split name is too long (max {MAX_HF_DATASET_OPTION_LENGTH} chars)

What it means

Raised by the _check_split_name field validator shared by train_split and eval_split: after trimming (empty normalizes to None), a split name longer than MAX_HF_DATASET_OPTION_LENGTH characters is rejected. Split names are short identifiers like 'train', 'test', 'train[:80%]', so an over-long value means the wrong data landed in the field. The length check fires before the character-validity check.

Source

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

            return None
        if len(v) > 4096:
            raise ValueError("local cache path is too long (max 4096 chars)")
        if "\x00" in v:
            raise ValueError("local cache path contains invalid characters")
        if ".." in Path(v).parts or ".." in PureWindowsPath(v).parts:
            raise ValueError("local cache path must not contain '..' segments")
        return v

    @field_validator("train_split", "eval_split")
    @classmethod
    def _check_split_name(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"split name is too long (max {MAX_HF_DATASET_OPTION_LENGTH} chars)")
        if not valid_hf_dataset_split_instruction(v):
            raise ValueError("split name contains invalid characters")
        return v

    @field_validator("learning_rate", mode = "before")
    @classmethod
    def _check_learning_rate(cls, v):
        # Stringify because downstream call sites float() it themselves.
        lr = _parse_lr(v)
        return str(lr)

    @field_validator("batch_size")
    @classmethod
    def _check_batch_size(cls, v: int) -> int:
        if v is None:
            raise ValueError("batch_size is required")
        if v < 1 or v > _MAX_BATCH_SIZE:
            raise ValueError(f"batch_size must be in [1, {_MAX_BATCH_SIZE}] (got {v!r})")

View on GitHub (pinned to 203007d190)

Solutions

1. Use a short split name or HF slice instruction, e.g. 'train' or 'train[:80%]'.
2. Check field mapping in the request builder — long content belongs elsewhere.
3. Omit eval_split if you do not want an eval phase (it normalizes to None).

Example fix

// before
{ train_split: "train,validation,test combined and shuffled" }
// after
{ train_split: "train[:80%]", eval_split: "train[80%:]" }

def split_names_short_enough(body: dict, max_len: int) -> bool:
    return all(len((body.get(f) or "").strip()) <= max_len for f in ("train_split", "eval_split"))

function splitsOk(body: { train_split?: string; eval_split?: string }, maxLen: number): boolean {
  return [body.train_split, body.eval_split].every(s => (s?.trim().length ?? 0) <= maxLen);
}

When it happens

Trigger: POST a training start request with train_split or eval_split longer than the configured max, e.g. an entire split-instruction script or a pasted error message in the field.

Common situations: UI free-text areas bound to split fields; users pasting documentation snippets; config systems that inline a list of splits into one field.

Related errors

• hf_dataset is too long (max 256 chars)
• hf_dataset contains invalid characters or path segments
• subset is too long (max {MAX_HF_DATASET_OPTION_LENGTH} chars
• subset contains invalid characters
• 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/6ad520c2b9307194. Report an issue: GitHub.