# your container will show unhealthy while serving perfectly

> The llama.cpp server image ships a healthcheck aimed at port 8080; start the server on another port and Docker marks the container unhealthy while it serves fine. Keep 8080 inside the container or override the check.

- Platform: Any local stack
- Runtime: llama.cpp server (Docker)
- Published: 2026-09-02
- Sources: https://agmind.ai/guides/deploy-llm-strix-halo/, https://agmind.ai/essays/dashboard-lies-both-directions/
- Canonical: https://agmind.ai/symptoms/container-unhealthy-while-serving-healthcheck-port/

## What you see

`docker ps` marks a running llama.cpp server container `unhealthy` while
the server behind it answers every real request. Restarting the container
changes nothing. `docker inspect` shows the built-in healthcheck probing
`localhost:8080/health`, and the server was started with `--port` set to
something else.

## Where we saw it

One of the lab boxes, mid-August 2026: two freshly deployed test models,
started on ports 8090 and 8091. Both containers showed unhealthy while
serving. The deployment guide links that incident as the trap in its own
Strix Halo path, which runs `ghcr.io/ggml-org/llama.cpp:server-vulkan` on
a Ryzen AI Max+ 395 box. Neither page records a build number for the image;
the guide pulls it by tag and tells you to re-pull by digest once it works.

## Cause

The image ships a default healthcheck that probes `localhost:8080/health`
inside the container. Pass a different `--port` and the server listens
there while the probe keeps asking 8080. Nobody answers, Docker stamps
`unhealthy` into the status column, and the column has no color for "the
probe is misconfigured", only for "dead". A restarted container inherits
the same probe, so it fails the same way.

## Fix

Two options from the guide: keep the internal port at 8080, or override the
healthcheck. The guide's serving command does the first, `--port 8080`
inside the container, published as `-p 8080:8080`:

```
docker run -d --name llm-server \
  --device /dev/dri --device /dev/kfd \
  -v /var/lib/llm/models:/models \
  -p 8080:8080 \
  ghcr.io/ggml-org/llama.cpp:server-vulkan \
  -m /models/YOUR-MODEL.gguf \
  -ngl 999 -fa on -c 32768 \
  --host 0.0.0.0 --port 8080 --jinja
```

If you must move `--port`, override the healthcheck to match; the guide
does not print that override. Then ask the process, not your command line,
on the host port you published (8080 with the guide's `-p 8080:8080`):

```
curl -s localhost:8080/props | python3 -m json.tool | head -40
```

That shows what the process runs: `n_ctx`, the model path, the slot count.
Whether it answers is the guide's next step, a real chat completion checked
for non-empty `content` and a `stop` finish reason.

Inside the lab harness the rule became: health checks target the exact
endpoint and port a cell is configured to use, and fail fast when it does
not answer.

## Still open upstream?

Not tracked by us. Neither source page names an upstream issue.

## Evidence

- [Deploy a local LLM on Strix Halo](https://agmind.ai/guides/deploy-llm-strix-halo/), Step 3,
  the port note next to the serving command.
- [The dashboard lied twice in one day, in opposite directions](https://agmind.ai/essays/dashboard-lies-both-directions/),
  "Red but fine", the incident as it happened.

---

Machine-readable claim registry: https://agmind.ai/claims.json · llms.txt: https://agmind.ai/llms.txt