{"record":{"id":"3a4421f307d70dac","repo":"docker/cli","slug":"health-start-period-cannot-be-negative","errorCode":null,"errorMessage":"--health-start-period cannot be negative","messagePattern":"--health-start-period cannot be negative","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/container/opts.go","lineNumber":588,"sourceCode":"\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,\n\t\t}\n\t}\n\n\tdeviceRequests := copts.gpus.Value()\n\tif len(cdiDeviceNames) > 0 {\n\t\tcdiDeviceRequest := container.DeviceRequest{","sourceCodeStart":570,"sourceCodeEnd":606,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/container/opts.go#L570-L606","documentation":"Returned when --health-start-period is set to a negative duration (opts.go:587-589). Registered via flags.DurationVar with a version annotation of 1.29 (opts.go:267-268). The start period gives a container grace time before retries count; a negative value is invalid and rejected within the haveHealthSettings branch.","triggerScenarios":"Running `docker run --health-start-period=-10s ...` or any negative duration while health settings are present. A parsed negative time.Duration triggers the guard.","commonSituations":"Typo'd minus sign; CI variable producing a negative; expecting 0 vs negative to mean different things (both effectively mean no grace period, but negative is rejected).","solutions":["Use a positive duration like --health-start-period=15s.","Use 0 (or omit) for no explicit start period.","Validate template arithmetic feeding this flag."],"exampleFix":"// before\ndocker run --health-start-period=-10s --health-cmd=/check.sh myimage\n// after\ndocker run --health-start-period=10s --health-cmd=/check.sh myimage","handlingStrategy":"validation","validationCode":"if copts.healthStartPeriod < 0 {\n    return errors.New(\"--health-start-period cannot be negative\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Reject negative durations in template rendering.","Use 0 to omit the start period.","Confirm daemon API >= 1.29 support."],"tags":["docker-cli","healthcheck","duration","negative-value","validation","container-create","api-version"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}