{"record":{"id":"c31e1a1538b31150","repo":"huggingface/transformers","slug":"the-server-running-on-url-returned-status-code","errorCode":null,"errorMessage":"The server running on {url} returned status code {output.status_code} on health check (/health).","messagePattern":"The server running on (.+?) returned status code (.+?) on health check \\(/health\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/cli/chat.py","lineNumber":390,"sourceCode":"            with open(examples_path) as f:\n                self.examples = yaml.safe_load(f)\n        else:\n            self.examples = DEFAULT_EXAMPLES\n\n        # Check requirements\n        if not is_rich_available():\n            raise ImportError(\"You need to install rich to use the chat interface. (`pip install rich`)\")\n\n        # Run chat session\n        asyncio.run(self._inner_run())\n\n    @staticmethod\n    def check_health(url):\n        health_url = urljoin(get_service_root_url(url) + \"/\", \"health\")\n        try:\n            output = httpx.get(health_url)\n            if output.status_code != 200:\n                raise ValueError(\n                    f\"The server running on {url} returned status code {output.status_code} on health check (/health).\"\n                )\n        except httpx.ConnectError:\n            raise ValueError(\n                f\"No server currently running on {url}. To run a local server, please run `transformers serve` in a\"\n                f\"separate shell. Find more information here: https://huggingface.co/docs/transformers/serving\"\n            )\n\n        return True\n\n    def handle_non_exit_user_commands(\n        self,\n        user_input: str,\n        interface: RichInterface,\n        examples: dict[str, dict[str, str]],\n        config: GenerationConfig,\n        chat: list[dict],\n    ) -> tuple[list[dict], GenerationConfig]:","sourceCodeStart":372,"sourceCodeEnd":408,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/cli/chat.py#L372-L408","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["curl the health endpoint yourself: curl <url>/health — expect 200","Wait until `transformers serve` prints that it is up, then retry chat","Fix the URL: use the exact host:port the server listens on (default localhost:8000), no extra path","If behind a proxy, add a route that forwards /health to the server"],"exampleFix":"# before\ntransformers chat --url http://localhost:8000/v1  # /v1/health -> 404\n\n# after\ntransformers chat --url http://localhost:8000","handlingStrategy":"retry","validationCode":"import httpx\n\nresp = httpx.get(\"http://localhost:8000/health\")\nif resp.status_code != 200:\n    print(f\"Server unhealthy ({resp.status_code}); fix server before chat\")","typeGuard":null,"tryCatchPattern":"import time, httpx\nfor _ in range(30):\n    try:\n        if httpx.get(f\"{url}/health\", timeout=2).status_code == 200:\n            break\n    except httpx.HTTPError:\n        pass\n    time.sleep(1)\nelse:\n    raise RuntimeError(\"server never became healthy\")","preventionTips":["Wait for the serve process to log readiness before launching chat","Hit /health with curl as a readiness probe in scripts","Use the exact host:port; strip path suffixes like /v1"],"tags":["cli","chat","health-check","network","valueerror"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}