huggingface/transformers · error · ValueError

The server running on {url} returned status code {output.sta

Error message

The server running on {url} returned status code {output.status_code} on health check (/health).

What it means

Before starting a chat session, ChatInterface.check_health issues GET {service_root}/health against the target server and expects HTTP 200. Any other status code raises ValueError with the returned code, meaning something is listening at the URL but it is not a healthy transformers server (or it is failing).

Source

Thrown at src/transformers/cli/chat.py:390

            with open(examples_path) as f:
                self.examples = yaml.safe_load(f)
        else:
            self.examples = DEFAULT_EXAMPLES

        # Check requirements
        if not is_rich_available():
            raise ImportError("You need to install rich to use the chat interface. (`pip install rich`)")

        # Run chat session
        asyncio.run(self._inner_run())

    @staticmethod
    def check_health(url):
        health_url = urljoin(get_service_root_url(url) + "/", "health")
        try:
            output = httpx.get(health_url)
            if output.status_code != 200:
                raise ValueError(
                    f"The server running on {url} returned status code {output.status_code} on health check (/health)."
                )
        except httpx.ConnectError:
            raise ValueError(
                f"No server currently running on {url}. To run a local server, please run `transformers serve` in a"
                f"separate shell. Find more information here: https://huggingface.co/docs/transformers/serving"
            )

        return True

    def handle_non_exit_user_commands(
        self,
        user_input: str,
        interface: RichInterface,
        examples: dict[str, dict[str, str]],
        config: GenerationConfig,
        chat: list[dict],
    ) -> tuple[list[dict], GenerationConfig]:

View on GitHub (pinned to a597f97485)

Solutions

1. curl the health endpoint yourself: curl <url>/health — expect 200
2. Wait until `transformers serve` prints that it is up, then retry chat
3. Fix the URL: use the exact host:port the server listens on (default localhost:8000), no extra path
4. If behind a proxy, add a route that forwards /health to the server

Example fix

# before
transformers chat --url http://localhost:8000/v1  # /v1/health -> 404

# after
transformers chat --url http://localhost:8000

import httpx

resp = httpx.get("http://localhost:8000/health")
if resp.status_code != 200:
    print(f"Server unhealthy ({resp.status_code}); fix server before chat")

import time, httpx
for _ in range(30):
    try:
        if httpx.get(f"{url}/health", timeout=2).status_code == 200:
            break
    except httpx.HTTPError:
        pass
    time.sleep(1)
else:
    raise RuntimeError("server never became healthy")

When it happens

Trigger: Pointing `transformers chat` at a URL where a different service or proxy answers (returning 404/502); the transformers server is still booting and the route is not mounted yet; the server crashed mid-request and the port is held by a middleware returning 503; wrong path prefix so /health hits another app.

Common situations: URL points to an nginx/traefik proxy without the right route; server launched seconds earlier and not yet ready; base URL includes or omits a path component (e.g. /v1) inconsistently with the server; port collision with another web app.

Related errors

• No server currently running on {url}. To run a local server,
• Failed to convert `generate_flags` into a valid JSON object.
• {lowercase_name} is not a valid model name
• Could not find TOC entry for {old_lowercase_name}
• You need to install `libcst` to run this command -> `pip ins

AI-assisted analysis of huggingface/transformers@a597f97485 (2026-08-14). Data as JSON: /api/errors/c31e1a1538b31150. Report an issue: GitHub.