Swarm Settings health check 'Test' field serializes as single string instead of JSON array, causing tasks to hang in 'Starting' forever

[ftxavier]

Description

The Health Check field under Advanced → Swarm Settings for an Application does not correctly serialize the Test array. Whatever string is pasted into the field ends up wrapped as a single-element array (a literal string), instead of being parsed as a proper Docker HEALTHCHECK Test array. This produces an invalid Swarm service healthcheck spec that Docker Engine rejects (Unknown healthcheck type '' (expected 'CMD')), which causes every task for the service to hang in Starting forever, which in turn blocks the service's internal DNS/VIP registration in the Swarm overlay network — the service becomes completely unroutable (Traefik gets NXDOMAIN resolving the service name) even though the underlying containers are running perfectly fine.

This is a nasty bug because:

1. The app itself is 100% healthy (verified by curling the container's IP directly).
2. docker service ls shows 0/N replicas indefinitely.
3. There is no user-facing error in the Dokploy UI — the deploy appears to just hang.
4. It also affects services that were never touched via the Advanced tab: a freshly-created Application via Dokploy's normal "create app" flow already ships with Healthcheck.Test: [""] (empty string) by default, which triggers the exact same Docker Engine warning and the exact same stuck-task/broken-DNS cascade — no manual healthcheck configuration is even required to hit this.

To Reproduce

1. Create an Application in Dokploy, deploy it normally (no custom healthcheck set).

2. Inspect the resulting Swarm service: docker service inspect <service> --format '{{json .Spec.TaskTemplate.ContainerSpec.Healthcheck}}' → shows {"Test":[""]}.

3. docker service ps <service> will (inconsistently, but reproducibly under load/repeated redeploys) show tasks stuck in Starting forever, and docker service ls never reaches the desired replica count.

4. Attempting to "fix" this by setting a Health Check in Advanced → Swarm Settings makes it worse in a different way. Example input pasted into the Test field:

   ["CMD","curl","-f","http://localhost:8080/"]

   (also tried the full object form {"Test":[...],"Interval":...} — same result for the Test portion)

   After clicking Deploy, the resulting live Swarm spec is:

   {"Test":["[\"CMD\",\"curl\",\"-f\",\"http://localhost:8080/\"]"],"Interval":10000000000,"Timeout":5000000000,"StartPeriod":5000000000,"Retries":3}

   Note Test has one element, and that element is the literal string I typed (brackets and all), not a 4-element array. Interval/Timeout/StartPeriod/Retries do get parsed correctly as numbers, so the numeric fields work — only Test is mishandled.

Current vs. Expected behavior

Current: Test field content is stored verbatim as a single array element, regardless of whether a JSON array or bare string is entered. Combined with the default Test: [""] on fresh services, this reliably produces Docker Engine's Unknown healthcheck type '' (expected 'CMD') warning and permanently stuck task convergence.

Expected: The Test field should either (a) accept and correctly parse a JSON array like ["CMD","curl","-f","http://localhost:8080/"] into a real multi-element Test array, or (b) if it's meant to be a single CMD-SHELL string, automatically wrap it as ["CMD-SHELL", "<input>"] rather than ["<input>"]. And by default (no health check configured), new services should get a semantically valid "no healthcheck" value (Test: ["NONE"]), not Test: [""].

Workaround

Bypass the Dokploy UI entirely and set the healthcheck directly via the Docker CLI against the already-created service:

docker service update --detach=false \
  --health-cmd "curl -f http://localhost:8080/ || exit 1" \
  --health-interval 10s \
  --health-timeout 5s \
  --health-retries 3 \
  --health-start-period 5s \
  <service-name>

This produces a correct {"Test":["CMD-SHELL","curl -f http://localhost:8080/ || exit 1"], ...} and the service converges immediately. Downside: the next time "Deploy" is clicked in the Dokploy UI for that app, it appears to re-apply the broken Test value from the stored (malformed) config, undoing the workaround.

Environment

• Dokploy version: v0.30.0
• Docker Engine version: 29.7.2
• Single-node Swarm
• Deployment type: Application (Dockerfile build → image pushed to GHCR → Dokploy pulls & deploys), start-first update order

Related issues

This seems adjacent to #4576 (endless restart loop with default healthcheck) and #3987 (Swarm rollback not reflected when tasks fail healthcheck) — all three point at the same general area (Docker Swarm healthcheck handling) being fragile, but this specific report is about the Test field losing its array structure when configured through the Advanced → Swarm Settings UI, plus the default Test: [""] on fresh services being invalid rather than a proper "no healthcheck" sentinel.

Impact

This caused a full production outage for us: a routine redeploy caused the frontend service to get permanently stuck at 0/N replicas with no visible error in the UI, and the service became completely unroutable (DNS NXDOMAIN for the service name inside the Swarm overlay network) even though the containers themselves were running and serving traffic correctly when hit directly by IP.

[linear-code]

DOK-685

[dosubot]

Hi @ftxavier! I'm Dosu and I'm helping the Dokploy team.

I've traced through the code and can confirm your findings. There are two distinct issues at play:

The Test field serialization (Bug 1)

The Health Check UI in health-check-form.tsx implements Test as a dynamic list of individual string inputs — each "Add Command" click appends one empty string to the array. There is no single text input that accepts a raw JSON array. So when you paste ["CMD","curl","-f","http://localhost:8080/"] into one field, it gets stored verbatim as a single-element array: ["[\"CMD\",\"curl\",\"-f\",\"http://localhost:8080/\"]"] [1]. The intended workflow is to click "Add Command" four times and enter CMD, curl, -f, http://localhost:8080/ into separate fields — but this is extremely non-obvious. The placeholder only shows CMD-SHELL for the first element, and the FormDescription confusingly shows a JSON array example [2]. This exact UX confusion was reported in #4385 as well.

Default Test: [""] on fresh services (Bug 2)

The form defaults Test to an empty array [] [3], and the onSubmit handler does have a hasAnyValue check that sends null when all fields are empty [4]. When healthCheckSwarm is null, generateConfigContainer assembles the Swarm service config without an explicit Healthcheck key [5]. However, as you've observed, Docker Engine can still end up with Test: [""] on the resulting service — this likely occurs when other swarm settings (like RestartPolicy or UpdateConfig) cause Docker to initialize the Healthcheck struct with empty defaults, or when an existing service is updated and inherits its previous healthcheck spec. The Test: [""] value is invalid because Docker expects the first element to be CMD, CMD-SHELL, or NONE, and an empty string triggers Unknown healthcheck type ''. This matches the pattern reported in #4576 where default healthcheck handling causes endless restart loops.

What needs to change

1. In generateConfigContainer, when healthCheckSwarm is null/absent, explicitly pass Healthcheck: { Test: ["NONE"] } to the Docker API rather than omitting the key. This prevents Docker from inheriting a stale or invalid Test value.
2. The "Clear" button in the form currently resets Test to [] [6] — it should instead save { Test: ["NONE"] } to explicitly disable the healthcheck.
3. The FormDescription and placeholder text should be updated to make clear that each array element goes in a separate input field, not pasted as JSON.

Your docker service update --health-cmd workaround is correct, but as you noted, each Dokploy redeploy re-applies healthCheckSwarm from the database [5], overwriting your fix. Until this is patched, you could also set the healthcheck properly through the UI by clicking "Add Command" twice and entering CMD-SHELL in the first field and curl -f http://localhost:8080/ || exit 1 in the second field, then saving — this should produce the correct Test: ["CMD-SHELL", "curl -f http://localhost:8080/ || exit 1"] array and survive redeploys.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[bestmaa]

Hi @ftxavier, I reproduced this in an isolated Docker 29.7.2 Swarm: Test: [""] left the service at 0/1 in Starting and Docker logged an unknown healthcheck type warning.

I opened #5205 with a fix that normalizes JSON arrays pasted into one field, converts a single command to CMD-SHELL, and maps legacy blank values to NONE. The same normalization also runs when the Docker service spec is generated, so existing stored values are covered.

The focused regression tests and Node 24 production build pass. In the after-test, pasted JSON, blank/disabled, and single-shell-command services all reached 1/1 Running without adding another invalid-healthcheck warning.

Please let me know if you would prefer a different input model or want any adjustments.