{"record":{"id":"f4741877a7c9d11f","repo":"docker/cli","slug":"health-timeout-cannot-be-negative","errorCode":null,"errorMessage":"--health-timeout cannot be negative","messagePattern":"--health-timeout cannot be negative","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/container/opts.go","lineNumber":582,"sourceCode":"\t\tcopts.healthTimeout != 0 ||\n\t\tcopts.healthStartPeriod != 0 ||\n\t\tcopts.healthRetries != 0 ||\n\t\tcopts.healthStartInterval != 0\n\tif copts.noHealthcheck {\n\t\tif haveHealthSettings {\n\t\t\treturn nil, errors.New(\"--no-healthcheck conflicts with --health-* options\")\n\t\t}\n\t\thealthConfig = &container.HealthConfig{Test: []string{\"NONE\"}}\n\t} else if haveHealthSettings {\n\t\tvar probe []string\n\t\tif copts.healthCmd != \"\" {\n\t\t\tprobe = []string{\"CMD-SHELL\", copts.healthCmd}\n\t\t}\n\t\tif copts.healthInterval < 0 {\n\t\t\treturn nil, errors.New(\"--health-interval cannot be negative\")\n\t\t}\n\t\tif copts.healthTimeout < 0 {\n\t\t\treturn nil, errors.New(\"--health-timeout cannot be negative\")\n\t\t}\n\t\tif copts.healthRetries < 0 {\n\t\t\treturn nil, errors.New(\"--health-retries cannot be negative\")\n\t\t}\n\t\tif copts.healthStartPeriod < 0 {\n\t\t\treturn nil, errors.New(\"--health-start-period cannot be negative\")\n\t\t}\n\t\tif copts.healthStartInterval < 0 {\n\t\t\treturn nil, errors.New(\"--health-start-interval cannot be negative\")\n\t\t}\n\n\t\thealthConfig = &container.HealthConfig{\n\t\t\tTest:          probe,\n\t\t\tInterval:      copts.healthInterval,\n\t\t\tTimeout:       copts.healthTimeout,\n\t\t\tStartPeriod:   copts.healthStartPeriod,\n\t\t\tStartInterval: copts.healthStartInterval,\n\t\t\tRetries:       copts.healthRetries,","sourceCodeStart":564,"sourceCodeEnd":600,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/container/opts.go#L564-L600","documentation":"Returned when --health-timeout is set to a negative duration (opts.go:581-583). Registered via flags.DurationVar (opts.go:266), the flag accepts parsed negative durations which are then rejected as invalid. The check runs only within the haveHealthSettings branch.","triggerScenarios":"Running `docker run --health-timeout=-2s ...` or any negative duration while health settings are present. The parser accepts the value, the guard rejects it.","commonSituations":"Typo'd minus sign in CI/CD variable; misreading documentation and passing a negative to mean \"no timeout\" (use 0 instead); templating that computes timeout as a negative delta.","solutions":["Use a positive duration like --health-timeout=5s.","Use 0 (or omit) for the daemon default timeout.","Audit template arithmetic that may produce negative durations."],"exampleFix":"// before\ndocker run --health-timeout=-2s --health-cmd=/check.sh myimage\n// after\ndocker run --health-timeout=2s --health-cmd=/check.sh myimage","handlingStrategy":"validation","validationCode":"if copts.healthTimeout < 0 {\n    return errors.New(\"--health-timeout cannot be negative\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Reject negative durations at the config/templating layer.","Use 0 for daemon default timeout.","Check computed timeout deltas for sign errors."],"tags":["docker-cli","healthcheck","duration","negative-value","validation","container-create"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}