{"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/e9452d6e785f6e365712b9d71bd7517591773c86/cli/command/container/opts.go#L564-L600","documentation":"The CLI validates that --health-timeout, the maximum time a single health probe may run before being considered failed, is not negative (opts.go:581-583). Like the other health durations it is a time.Duration where 0 means 'daemon default', so negative values are rejected client-side.","triggerScenarios":"`docker run --health-cmd '...' --health-timeout=-1s image`, or any run/create where a health flag is set and the timeout duration parses negative (e.g. from an environment-variable expansion).","commonSituations":"Using -1 to try to mean 'no timeout'; arithmetic in wrapper scripts producing negative durations; confusion with APIs where -1 is a sentinel.","solutions":["Provide a positive timeout, e.g. --health-timeout=5s","Omit the flag or pass 0 to use the default timeout","For a very long probe, set a large positive value instead of a negative sentinel"],"exampleFix":"# before\ndocker run --health-cmd 'curl -f localhost' --health-timeout=-1s myimage\n# after\ndocker run --health-cmd 'curl -f localhost' --health-timeout=30s myimage","handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":["docker-cli","healthcheck","duration","flag-validation"],"analyzedSha":"e9452d6e785f6e365712b9d71bd7517591773c86","analyzedAt":"2026-08-01T07:09:22.474Z","schemaVersion":2}