unslothai/unsloth · error · ValueError

extra llama-server args cannot contain a bare value ('{token

Error message

extra llama-server args cannot contain a bare value ('{token[:64]}'); every value must follow its flag

What it means

ValueError from llama_server_args.py:285 — a token that is not flag-shaped (bare value) appears while pending_values <= 0, i.e. no preceding flag is expecting a value. Today's llama-server rejects positional arguments with 'invalid argument' (a failed load, not a 400), and a build that did accept positionals would read one as the model path — exactly what the -m/--model denial exists to prevent. So the module insists every value follow its flag.

Source

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

            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():
            # _flag_name strips before it looks anything up, so a quoted "--top-k "
            # passed the denylist and the arity walk as --top-k and then went to the
            # child with the space still on it. llama.cpp looks the whole token up,
            # so it answers "error: invalid argument: --top-k" (measured on b10342),
            # naming a flag that looks correct in the log. Only flag-shaped tokens:
            # a VALUE may legitimately end in whitespace, a chat template or a
            # grammar being the obvious ones.
            raise ValueError(
                f"llama-server does not accept the spaces around '{token[:64]}': "
                f"write it as '{flag}'"
            )

View on GitHub (pinned to 203007d190)

Solutions

  1. Fix the pairing: every value must directly follow the flag that owns it — verify with a walk that flags and values alternate correctly.
  2. Rebuild the list from a canonical structure ({'--top-k': '40'} dict → flag,value pairs) instead of string surgery.
  3. If the first token is bare, a flag is missing — check that flag names start with - and were not eaten by quote handling.
  4. Use shlex.split on the original quoted string so flag/value pairing survives.

Example fix

# before
extra_args = ["40", "--top-k", "--flash-attn", "on"]  # '40' is bare

# after
extra_args = ["--top-k", "40", "--flash-attn", "on"]
Defensive patterns

Strategy: validation

Validate before calling

def flags_and_values_pair_up(tokens):
    owed = 0
    for t in tokens:
        if _flag_name(t) is not None:
            owed = 1  # approximation: ordinary flags take one value
        elif owed > 0:
            owed -= 1
        else:
            return False
    return True

Type guard

def no_bare_leading_value(tokens) -> bool:
    return _flag_name(tokens[0]) is not None if tokens else True

Try / catch

try:
    validate_extra_args(args)
except ValueError as e:
    if "bare value" in str(e):
        raise HTTPException(400, "every value must follow its flag")
    raise

Prevention

When it happens

Trigger: A value token with no owning flag: the first token in the list is a value; two values follow a one-value flag ('--top-k 40 60'); a flag and its value got separated by a denied flag removal or bad splitting of a quoted shell line.

Common situations: Splitting a quoted shell command with shlex incorrectly (quotes consumed, pairing lost); deleting a flag from a stored config but leaving its value; pasting '40 --top-k' with the value first; a UI saving values and flags in separate fields and interleaving them wrongly.

Related errors

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