unslothai/unsloth · error · ValueError

llama-server flag '{flag}' is managed by Unsloth Studio and

Error message

llama-server flag '{flag}' is managed by Unsloth Studio and cannot be passed as an extra arg

What it means

ValueError from llama_server_args.py:274 — a flag-shaped token whose name (after _flag_name normalization) is in _DENYLIST. Unsloth Studio manages certain llama-server flags itself (--model/-m, context/cache/GPU-layer controls, etc.); letting the user override them would break model switching, sidestep the native-path lease, or fight the studio's own lifecycle. The denial message names the exact flag.

Source

Thrown at studio/backend/core/inference/llama_server_args.py:274

        # subprocess.Popen raise while it encodes argv, long after the load has begun
        # switching models. Refused at the boundary, where it is still a 400.
        try:
            encoded = token.encode("utf-8")
        except UnicodeEncodeError as error:
            raise ValueError(
                "extra llama-server args cannot contain unpaired surrogate characters"
            ) from error
        total_bytes += len(encoded)
        limit = max_extra_args_bytes()
        if total_bytes > limit:
            raise ValueError(f"extra llama-server args are too large (limit {limit} bytes)")
        # execve rejects a NUL outright; the rest would reach the child's parser as
        # invisible characters and be blamed on the flag they are attached to.
        if _has_control_characters(token):
            raise ValueError("extra llama-server args cannot contain control characters")
        flag = _flag_name(token)
        if flag is not None and flag in _DENYLIST:
            raise ValueError(
                f"llama-server flag '{flag}' is managed by Unsloth Studio "
                f"and cannot be passed as an extra arg"
            )
        if flag is None:
            # A token belonging to no flag. Today's llama-server answers "invalid
            # argument" and refuses to start, which is a failed load rather than a
            # 400, and a build that did accept a positional would read it as the
            # model path: that is the one thing the -m / --model denial exists to
            # prevent, and it would sidestep the native-path lease as well.
            if pending_values <= 0:
                raise ValueError(
                    "extra llama-server args cannot contain a bare value "
                    f"('{token[:64]}'); every value must follow its flag"
                )
            pending_values -= 1
            if pending_two_value > 0:
                pending_two_value -= 1
        elif token != token.strip():

View on GitHub (pinned to 203007d190)

Solutions

Remove the denied flag from extra args and set the equivalent through the studio's own UI/API fields (context size, GPU layers, cache type all have first-class controls).
Check the message for the exact flag name; watch for alternate spellings (-m vs --model, underscores vs dashes) that normalize to the same denied flag.
If you genuinely need a managed parameter changed, look for the dedicated config key rather than the raw flag.
Use drop_managed_flags() to split stored args into what still loads vs what was removed when migrating old configs.

Example fix

# before
extra_args = ["--model", "/other/model.gguf", "--top-k", "40"]

# after
extra_args = ["--top-k", "40"]
# set the model through the studio's model-selection API instead

Defensive patterns

Strategy: validation

Validate before calling

from core.inference.llama_server_args import drop_managed_flags
kept, removed = drop_managed_args = drop_managed_flags(extra_args)
if removed:
    warn(f"removed studio-managed flags: {removed}")

Type guard

def is_managed_flag(token) -> bool:
    name = _flag_name(token)
    return name is not None and name in _DENYLIST

Try / catch

try:
    validate_extra_args(args)
except ValueError as e:
    if "managed by Unsloth Studio" in str(e):
        raise HTTPException(400, "set model/ctx via studio settings, not extra args")
    raise

Prevention

Never paste a full llama-server launch line into extra args; only pass knobs the studio does not own.
Set model path, context size, cache type, GPU layers through their dedicated studio settings.
Run drop_managed_flags() on imported/stored configs to clean them once.
Remember underscore/dash and -m/--model spellings normalize to the same denied flag.

When it happens

Trigger: Including a managed flag in extra args: -m/--model (would redirect the model path and bypass the path lease), or flags the studio sets itself such as context-size, cache, split-mode overrides (the same families parse_ctx_override/parse_cache_override/parse_split_mode/parse_gpu_layers_override handle).

Common situations: Copy-pasting a full llama-server launch line into the extra-args field; trying to force --ctx-size or -ngl through extra args because a UI control exists for it already; underscore/case spellings (--ctx_size) that _flag_name normalizes to the denied name.

Related errors

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