unslothai/unsloth · error · ValueError

local cache path is too long (max 4096 chars)

Error message

local cache path is too long (max 4096 chars)

What it means

Raised by the _check_cache_local_path field validator, which applies to four fields (model_local_path, dataset_local_path, model_snapshot_path, dataset_snapshot_path). These server-side cache paths are capped at 4096 characters after trimming — beyond the common PATH_MAX bound, so the OS would reject them anyway; validating here gives a clean 422 instead of a deep filesystem error. Empty-after-trim normalizes to None.

Source

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

        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:
            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")

View on GitHub (pinned to 203007d190)

Solutions

1. Fix the path construction bug producing the over-long value; the real paths should be short server cache locations.
2. If these fields are meant to be left to the server, omit them entirely.
3. Add a client-side length assertion on path fields before submit to catch runaway concatenation early.

Example fix

# before (loop appends each time)
path = f"{path}/{run_id}"  # grows unbounded
# after
path = base_cache_dir / run_id

PATH_FIELDS = ("model_local_path", "dataset_local_path", "model_snapshot_path", "dataset_snapshot_path")

def paths_short_enough(body: dict) -> bool:
    return all(len((body.get(f) or "").strip()) <= 4096 for f in PATH_FIELDS)

const PATH_FIELDS = ['model_local_path','dataset_local_path','model_snapshot_path','dataset_snapshot_path'] as const;
function pathsOk(body: Record<string, string | undefined>): boolean {
  return PATH_FIELDS.every(f => (body[f]?.trim().length ?? 0) <= 4096);
}

When it happens

Trigger: POST a training start request with any of the four path fields exceeding 4096 chars, e.g. a path that has been repeatedly re-joined onto itself or contains a huge base64 blob.

Common situations: Loop bugs that append a directory each iteration; embedding non-path payloads into a path field; extremely deep workspace trees; client mapping the wrong object into the path field.

Related errors

• Path does not exist
• Path must be a directory, not a file
• Path is not readable
• The filesystem root cannot be registered
• 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/6c4fddc7007b329d. Report an issue: GitHub.