{"record":{"id":"f2c6200ac1872488","repo":"apache/beam","slug":"max-num-workers-d-cannot-be-negative","errorCode":null,"errorMessage":"max_num_workers (%d) cannot be negative","messagePattern":"max_num_workers \\((.+?)\\) cannot be negative","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"sdks/go/pkg/beam/runners/dataflow/dataflowlib/job.go","lineNumber":442,"sourceCode":"\t\treturn errors.New(\"experiment worker_region and option workerZone are mutually exclusive\")\n\t}\n\tif hasExperimentWorkerRegion && opts.Zone != \"\" {\n\t\treturn errors.New(\"experiment worker_region and option Zone are mutually exclusive\")\n\t}\n\n\tif opts.Zone != \"\" {\n\t\tlog.Warn(ctx, \"Option --zone is deprecated. Please use --workerZone instead.\")\n\t\topts.WorkerZone = opts.Zone\n\t\topts.Zone = \"\"\n\t}\n\n\tnumWorkers := opts.NumWorkers\n\tmaxNumWorkers := opts.MaxNumWorkers\n\tif numWorkers < 0 {\n\t\treturn fmt.Errorf(\"num_workers (%d) cannot be negative\", numWorkers)\n\t}\n\tif maxNumWorkers < 0 {\n\t\treturn fmt.Errorf(\"max_num_workers (%d) cannot be negative\", maxNumWorkers)\n\t}\n\tif numWorkers > 0 && maxNumWorkers > 0 && numWorkers > maxNumWorkers {\n\t\treturn fmt.Errorf(\"num_workers (%d) cannot exceed max_num_workers (%d)\", numWorkers, maxNumWorkers)\n\t}\n\treturn nil\n}\n","sourceCodeStart":424,"sourceCodeEnd":449,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/go/pkg/beam/runners/dataflow/dataflowlib/job.go#L424-L449","documentation":"validateWorkerSettings in dataflowlib also rejects a negative opts.MaxNumWorkers before submitting to Dataflow, since the API requires non-negative worker settings. The job fails at translation time with 'max_num_workers (%d) cannot be negative'.","triggerScenarios":"Submitting a Dataflow job with PipelineOptions.MaxNumWorkers set below zero — usually from unparsed/negative flag input or arithmetic producing a negative cap, or a -1 sentinel meaning 'no cap'.","commonSituations":"Config file or CLI passing --max-num-workers=-1 to mean unlimited; computing max from quotas that resolved to negative; copy-pasted defaults containing -1.","solutions":["Set MaxNumWorkers to 0 (no cap enforced by this check) or a positive integer; never use -1 as a sentinel.","Validate/clamp the value at config parse time, e.g. if v < 0 { v = 0 }.","Ensure NumWorkers <= MaxNumWorkers when both are positive, or the subsequent check will also fail.","Fix quota/derivation logic that can yield a negative max."],"exampleFix":"// before\nopts.MaxNumWorkers = -1 // meant \"unlimited\"\n// max_num_workers (-1) cannot be negative\n\n// after\nopts.MaxNumWorkers = 0 // unset => Dataflow default cap","handlingStrategy":"validation","validationCode":"if opts.MaxNumWorkers < 0 {\n    return errors.New(\"max_num_workers must be >= 0 (0 = unset)\")\n}\nif opts.NumWorkers > 0 && opts.MaxNumWorkers > 0 && opts.NumWorkers > opts.MaxNumWorkers {\n    return errors.New(\"num_workers exceeds max_num_workers\")\n}","typeGuard":"func maxNumWorkersOk(n int) bool { return n >= 0 }","tryCatchPattern":null,"preventionTips":["Treat 0 as the unset sentinel for MaxNumWorkers, never -1.","Cross-check NumWorkers <= MaxNumWorkers in config validation before submit.","Add an options preflight function run before dataflowlib.Translate in all submit paths."],"tags":["dataflow","config-validation","pipeline-options","workers"],"backgroundTag":"invalid-config-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}