Repository navigation
Description
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:
- The app itself is 100% healthy (verified by curling the container's IP directly).
docker service lsshows0/Nreplicas indefinitely.- There is no user-facing error in the Dokploy UI — the deploy appears to just hang.
- 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
-
Create an Application in Dokploy, deploy it normally (no custom healthcheck set).
-
Inspect the resulting Swarm service:
docker service inspect <service> --format '{{json .Spec.TaskTemplate.ContainerSpec.Healthcheck}}'→ shows{"Test":[""]}. -
docker service ps <service>will (inconsistently, but reproducibly under load/repeated redeploys) show tasks stuck inStartingforever, anddocker service lsnever reaches the desired replica count. -
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
Testhas one element, and that element is the literal string I typed (brackets and all), not a 4-element array.Interval/Timeout/StartPeriod/Retriesdo get parsed correctly as numbers, so the numeric fields work — onlyTestis 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-firstupdate 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.
Activity
linear-code commentedon Aug 24, 2026
DOK-685
dosubot commentedon Aug 24, 2026
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
Testfield serialization (Bug 1)The Health Check UI in
health-check-form.tsximplementsTestas 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 enterCMD,curl,-f,http://localhost:8080/into separate fields — but this is extremely non-obvious. The placeholder only showsCMD-SHELLfor the first element, and theFormDescriptionconfusingly 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
Testto an empty array[][3], and theonSubmithandler does have ahasAnyValuecheck that sendsnullwhen all fields are empty [4]. WhenhealthCheckSwarmisnull,generateConfigContainerassembles the Swarm service config without an explicitHealthcheckkey [5]. However, as you've observed, Docker Engine can still end up withTest: [""]on the resulting service — this likely occurs when other swarm settings (likeRestartPolicyorUpdateConfig) cause Docker to initialize theHealthcheckstruct with empty defaults, or when an existing service is updated and inherits its previous healthcheck spec. TheTest: [""]value is invalid because Docker expects the first element to beCMD,CMD-SHELL, orNONE, and an empty string triggersUnknown healthcheck type ''. This matches the pattern reported in #4576 where default healthcheck handling causes endless restart loops.What needs to change
generateConfigContainer, whenhealthCheckSwarmis null/absent, explicitly passHealthcheck: { Test: ["NONE"] }to the Docker API rather than omitting the key. This prevents Docker from inheriting a stale or invalidTestvalue.Testto[][6] — it should instead save{ Test: ["NONE"] }to explicitly disable the healthcheck.FormDescriptionand 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-cmdworkaround is correct, but as you noted, each Dokploy redeploy re-applieshealthCheckSwarmfrom 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 enteringCMD-SHELLin the first field andcurl -f http://localhost:8080/ || exit 1in the second field, then saving — this should produce the correctTest: ["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 commentedon Aug 28, 2026
Hi @ftxavier, I reproduced this in an isolated Docker 29.7.2 Swarm:
Test: [""]left the service at0/1inStartingand 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 toNONE. 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 Runningwithout adding another invalid-healthcheck warning.Please let me know if you would prefer a different input model or want any adjustments.
jhthompson commentedon Oct 4, 2026
I ran into this today too. The workaround I found was to add two entries to the list (I'm unclear if this is what the instructions were trying to tell me to do).
My expectation based on the instructions were to have one entry like
["CMD-SHELL", "curl -f http:localhost:8000/health/"].I think the better UX would be to just have to enter one entry like
curl -f http:localhost:8000/health/, and the instruction above updated to clearly reflect that.