sgl-project/sglang · error · RuntimeError

resolution already failed on this ServerArgs; the handlers t

Error message

resolution already failed on this ServerArgs; the handlers that ran left their writes on the record, and a second pass would read that partial output as fresh input. Build a new record from the corrected arguments.

What it means

ServerArgs resolution (the pipeline of _handle_* handlers that derives defaults and cross-checks fields) is one-shot: if it fails midway, some handlers have already mutated the ServerArgs record. resolve_once() refuses a second pass so that partial writes are never mistaken for user-supplied input, and demands a fresh ServerArgs built from corrected arguments.

Source

Thrown at python/sglang/srt/server_args.py:3690

        resolve it itself -- stays raw.
        """

    def resolve_once(self) -> None:
        """Run the resolution pipeline, unless this record has been through it.

        Resolution is a deterministic function of the raw inputs -- two records
        built from the same arguments declare the same things -- but the
        handlers do not survive a second pass over their own output: DP
        attention halves ``chunked_prefill_size`` again on every re-entry.

        The publishing entry of every process calls this. In a child the record
        arrived by pickle and brought its declarations along, so the child has
        nothing left to derive and projects what the parent decided.
        """
        if getattr(self, "_resolution_finished", False):
            return
        if getattr(self, "_resolution_failed", False):
            raise RuntimeError(
                "resolution already failed on this ServerArgs; the handlers that "
                "ran left their writes on the record, and a second pass would "
                "read that partial output as fresh input. Build a new record "
                "from the corrected arguments."
            )
        try:
            self._run_resolution_pipeline()
        except BaseException:
            # The handlers that ran already declared, and they are not
            # idempotent over their own output.
            self._resolution_failed = True
            raise
        # Set here too, because the dummy/absent-model path returns before the
        # end of the pipeline that normally sets it: the gate is about whether
        # the handlers ran, not how far they got.
        self._resolution_finished = True

    def resolved_dict(self) -> Dict[str, Any]:

View on GitHub (pinned to 0132848349)

Solutions

Construct a brand-new ServerArgs (or a deep copy of the pristine pre-resolution arguments) with the corrected values and resolve that.
If retrying programmatically, keep the original kwargs dict and rebuild ServerArgs from it on each attempt.
Never reuse an instance whose resolution previously raised.

Example fix

# before
args = ServerArgs(model="m", tp_size=99)
try:
    run(args)
except ValueError:
    args.tp_size = 1
    run(args)  # RuntimeError: resolution already failed
# after
kwargs = {"model": "m", "tp_size": 99}
try:
    run(ServerArgs(**kwargs))
except ValueError:
    run(ServerArgs(**{**kwargs, "tp_size": 1}))

Defensive patterns

Strategy: fallback

Validate before calling

# keep pristine kwargs and always rebuild
server_kwargs = {"model": "m", "tp_size": 8}
def build_args():
    return ServerArgs(**server_kwargs)  # fresh record each attempt

Try / catch

try:
    resolve(server_args)
except (ValueError, RuntimeError) as e:
    log.warning('launch failed: %s; rebuilding ServerArgs', e)
    server_args = ServerArgs(**corrected_kwargs)  # never patch+retry the old object

Prevention

Treat ServerArgs as single-use once resolution has run.
Store the original kwargs dict, not the object, for retries.

When it happens

Trigger: Catching a ValueError from server launch (e.g. inside launch_or_reuse_server or a test harness), mutating the same ServerArgs object to fix the field, and calling resolve/launch again on it.

Common situations: Retry loops in deployment scripts or tests that catch a config error, patch the offending attribute, and relaunch with the same object; in-process embeddings/server helpers that reuse ServerArgs across attempts.

Related errors

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/6f03e0856fd0ab32. Report an issue: GitHub.