unslothai/unsloth · error · ValueError

extra llama-server args are too long for a Windows command l

Error message

extra llama-server args are too long for a Windows command line ({serialized} characters after quoting, limit {budget})

What it means

ValueError from llama_server_args.py:350 — Windows-only: after the per-token walk, the list is serialized with proper quoting via windows_command_length(out) and compared against WINDOWS_COMMAND_LIMIT minus WINDOWS_COMMAND_RESERVE (CreateProcess has a ~32k character command-line ceiling; the reserve leaves headroom). Excessively long or heavily-quoted extra args (quotes multiply: every embedded quote doubles in Windows quoting rules) exceed the budget and are refused before spawn, as a 400.

Source

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

                # insists on the second token.
                pending_values = 1 if attached else 2
                pending_two_value = 0
            else:
                pending_values = 0 if attached else 1
                pending_two_value = 0
            two_value_flag = flag
        out.append(token)
    if pending_two_value > 0:
        # Only this shape is checkable: an ordinary flag's arity is unknown here, so
        # a list ending in one is left to llama-server. START without END is a launch
        # that fails on the command line rather than a request that fails here.
        raise ValueError(f"llama-server flag '{two_value_flag}' takes two values")
    if sys.platform == "win32":
        # After the per-token walk, because this is a property of the whole list.
        serialized = windows_command_length(out)
        budget = WINDOWS_COMMAND_LIMIT - WINDOWS_COMMAND_RESERVE
        if serialized > budget:
            raise ValueError(
                "extra llama-server args are too long for a Windows command line "
                f"({serialized} characters after quoting, limit {budget})"
            )
    parse_ctx_override(out)
    parse_cache_override(out)
    parse_split_mode_override(out)
    parse_gpu_layers_override(out)
    return out


def drop_managed_flags(args: Optional[Iterable[str]]) -> tuple[list[str], list[str]]:
    """Split stored args into what still loads and the flag names removed.

    For the paths that CARRY OVER an existing value rather than receive a new one.
    The denylist grows (``--agent`` and the MCP flags were added once a text box
    made them one paste away), so an override saved by an older build can hold a
    name that is refused today. Refusing there punishes a user for a decision made
    later: the load, or the save of an unrelated setting, fails naming a flag they

View on GitHub (pinned to 203007d190)

Solutions

1. Move long payloads (grammars, schemas, chat templates) to files and pass the file path — one short, quote-light token.
2. Reduce token count / prefer values without spaces and embedded quotes to shrink the quoted serialization.
3. Compare your serialized length: the error reports exact characters vs budget; aim comfortably under because the reserve exists for a reason.
4. On non-Windows hosts this check never fires — if you control the platform, host llama-server args generation on Linux.

Example fix

# before
extra_args = ["--grammar", "root ::= " + big_grammar_with_quotes]  # explodes when quoted

# after
extra_args = ["--grammar-file", "C:\\models\\grammars\\big.gbnf"]

import sys
if sys.platform == "win32":
    from core.inference.llama_server_args import windows_command_length, WINDOWS_COMMAND_LIMIT, WINDOWS_COMMAND_RESERVE
    if windows_command_length(extra_args) > WINDOWS_COMMAND_LIMIT - WINDOWS_COMMAND_RESERVE:
        raise HTTPException(400, "too long for Windows; move payloads to files")

def fits_windows_cmdline(tokens) -> bool:
    return windows_command_length(tokens) <= WINDOWS_COMMAND_LIMIT - WINDOWS_COMMAND_RESERVE

try:
    validate_extra_args(args)
except ValueError as e:
    if "Windows command line" in str(e):
        raise HTTPException(400, "shorten args or use file paths for large values")
    raise

When it happens

Trigger: Running the studio on Windows with extra args whose quoted serialization exceeds the limit: many tokens, long values, or values full of characters that force quoting (spaces, quotes, backslashes) so the serialized length balloons past the raw length.

Common situations: Inline grammar/schema/chat-template strings with lots of quotes and spaces on Windows; a token count that fits MAX_EXTRA_ARG_TOKENS and the byte cap but whose QUOTED form is much longer; paths with spaces forcing quotes everywhere.

Related errors

• too many extra llama-server args (limit {MAX_EXTRA_ARG_TOKEN
• extra llama-server args cannot contain unpaired surrogate ch
• extra llama-server args are too large (limit {limit} bytes)
• extra llama-server args cannot contain control characters
• llama-server flag '{flag}' is managed by Unsloth Studio and

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