{"record":{"id":"3c12126bc016ac2b","repo":"apache/beam","slug":"num-workers-d-cannot-exceed-max-num-workers-d","errorCode":null,"errorMessage":"num_workers (%d) cannot exceed max_num_workers (%d)","messagePattern":"num_workers \\((.+?)\\) cannot exceed max_num_workers \\((.+?)\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"sdks/go/pkg/beam/runners/dataflow/dataflowlib/job.go","lineNumber":445,"sourceCode":"\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":427,"sourceCodeEnd":449,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/go/pkg/beam/runners/dataflow/dataflowlib/job.go#L427-L449","documentation":"validateWorkerSettings in the Dataflow runner translation layer checks that requested worker counts are sane before submitting a job to Google Cloud Dataflow. This error means the user asked for a number of workers larger than the declared maximum, which Dataflow would reject or which indicates contradictory options. The library fails fast at translation time instead of sending a bad job to the service.","triggerScenarios":"Calling beam.Run with a Dataflow pipeline where the num_workers option (NumWorkers) is > 0 and max_num_workers (MaxNumWorkers) is also > 0 but smaller than num_workers, e.g. --num_workers=100 --max_num_workers=50.","commonSituations":"Autoscaling configs where MaxNumWorkers was lowered (or left from a copied pipeline config) but NumWorkers was not adjusted; scripts templating worker counts where num_workers > max; setting NumWorkers after another config layer already set MaxNumWorkers lower.","solutions":["Lower num_workers so it is <= max_num_workers, or raise max_num_workers to at least num_workers","Remove the explicit num_workers option and rely on autoscaling with max_num_workers only","Check the flag/config source for both values and make the template set them consistently"],"exampleFix":"// before\npOpts = append(pOpts, beampipeoption.WithNumWorkers(100), beampipeoption.WithMaxNumWorkers(50))\n// after\npOpts = append(pOpts, beampipeoption.WithNumWorkers(50), beampipeoption.WithMaxNumWorkers(50))","handlingStrategy":"validation","validationCode":"if numWorkers > 0 && maxNumWorkers > 0 && numWorkers > maxNumWorkers {\n    return fmt.Errorf(\"num_workers (%d) must be <= max_num_workers (%d)\", numWorkers, maxNumWorkers)\n}","typeGuard":null,"tryCatchPattern":"if err := validateWorkerSettings(numWorkers, maxNumWorkers); err != nil {\n    return fmt.Errorf(\"invalid worker settings: %w\", err)\n}","preventionTips":["Always set num_workers and max_num_workers together from one config source","Add a CI check asserting numWorkers <= maxNumWorkers in deploy configs","Prefer autoscaling (set only max_num_workers) unless a fixed worker count is required"],"tags":["dataflow","go","configuration","worker-settings"],"backgroundTag":"conflicting-config-options","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"}