mlflow/mlflow · error · RuntimeError

Wait scoring server ready timeout.

Error message

Wait scoring server ready timeout.

What it means

wait_server_ready() loops until either the server responds or `timeout` seconds elapse; after breaking out of the loop it unconditionally raises RuntimeError('Wait scoring server ready timeout.'). It means the server never answered the health probe within the allotted time while the process itself was still alive.

Source

Thrown at mlflow/pyfunc/scoring_server/client.py:74

        return resp_status.text

    def wait_server_ready(self, timeout=30, scoring_server_proc=None):
        begin_time = time.time()

        while True:
            time.sleep(0.3)
            try:
                self.ping()
                return
            except Exception:
                pass
            if time.time() - begin_time > timeout:
                break
            if scoring_server_proc is not None:
                return_code = scoring_server_proc.poll()
                if return_code is not None:
                    raise RuntimeError(f"Server process already exit with returncode {return_code}")
        raise RuntimeError("Wait scoring server ready timeout.")

    def invoke(self, data, params: dict[str, Any] | None = None):
        """
        Args:
            data: Model input data.
            params: Additional parameters to pass to the model for inference.

        Returns:
            :py:class:`PredictionsResponse <mlflow.deployments.PredictionsResponse>` result.
        """
        response = requests.post(
            url=self.url_prefix + "/invocations",
            data=dump_input_data(data, params=params),
            headers={"Content-Type": scoring_server.CONTENT_TYPE_JSON},
        )
        if response.status_code != 200:
            raise Exception(
                f"Invocation failed (error code {response.status_code}, response: {response.text})"

View on GitHub (pinned to 6a27f2decc)

Solutions

1. Increase the timeout argument (e.g. wait_server_ready(timeout=300)) for slow-loading models
2. Verify url_prefix host/port match the server's --host/--port
3. Pass scoring_server_proc so early crashes fail fast with returncode instead of timing out
4. Check server logs to confirm it is actually listening; add retries around startup

Example fix

// before
client.wait_server_ready()  # default 30s
// after
client.wait_server_ready(timeout=300, scoring_server_proc=proc)

import socket

def port_open(host: str, port: int) -> bool:
    with socket.socket() as s:
        s.settimeout(2)
        return s.connect_ex((host, port)) == 0

try:
    client.wait_server_ready(timeout=300, scoring_server_proc=proc)
except RuntimeError as e:
    if "timeout" in str(e):
        print("server alive but not ready in 300s; check logs", proc.stdout.read())
    raise

When it happens

Trigger: Calling wait_server_ready() when the scoring server takes longer than `timeout` (default 30s) to start listening — slow model load, cold start, heavy dependency import — or when the client is polling the wrong host/port.

Common situations: Large models or slow disk making startup exceed 30s; wrong port/host in url_prefix so pings never succeed; server bound to localhost but client using container hostname.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Request timeout after ${timeout}ms
• Request timeout after ${effectiveTimeout}ms
• Authentication check timed out
• Connection check timed out
• The provider has timed out while generating a response to yo

AI-assisted analysis of mlflow/mlflow@6a27f2decc (2026-08-29). Data as JSON: /api/errors/420238e190f51a23. Report an issue: GitHub.