cannot use option zone with workerZone; prefer workerZone

Error message

cannot use option zone with workerZone; prefer workerZone

What it means

validateWorkerSettings rejects a configuration that sets both the deprecated --zone option and the newer --worker_zone option. Both request zonal placement, so they conflict; the library asks users to use worker_zone only, as zone is deprecated.

Solutions

Delete --zone and keep only --worker_zone.
Ensure zone and worker_zone point at the same zone if tooling sets both automatically — or strip the legacy flag.
Heed the deprecation: always prefer --worker_zone going forward.

Example fix

// before
// --zone=us-central1-a --worker_zone=us-central1-a
// after
// --worker_zone=us-central1-a

Defensive patterns

Strategy: validation

Validate before calling

if opts.Zone != "" && opts.WorkerZone != "" {
    opts.Zone = "" // worker_zone wins; zone is deprecated
}

Try / catch

if err := dataflowlib.ValidateWorkerSettings(ctx, opts); err != nil && strings.Contains(err.Error(), "option zone with workerZone") {
    // drop deprecated zone flag and retry
}

Prevention

Delete --zone from all scripts/templates; use --worker_zone only.
In wrappers, copy zone into worker_zone automatically for backward compatibility.
Grep repos and pipeline templates for "--zone=" during Beam upgrades.

When it happens

Trigger: JobOptions with Zone != "" AND WorkerZone != ""; e.g. passing --zone=us-central1-a together with --worker_zone=us-central1-b, or a wrapper that sets both fields before Translate.

Common situations: Migrating scripts from --zone to --worker_zone where the old flag was left in place; CI configs accumulating flags across Beam version upgrades.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/f055a9c63880d69a. Report an issue: GitHub.

Appendix: source

Thrown at sdks/go/pkg/beam/runners/dataflow/dataflowlib/job.go:406

	addIfNonEmpty("worker_zone", opts.WorkerZone)
	addIfNonEmpty("network", opts.Network)
	addIfNonEmpty("subnetwork", opts.Subnetwork)
	addIfNonEmpty("machine_type", opts.MachineType)
	addIfNonEmpty("container_images", strings.Join(images, ","))
	addIfNonEmpty("temp_location", opts.TempLocation)

	for k, v := range opts.Options.Options {
		ret = append(ret, newDisplayData(k, "", "go_options", v))
	}
	return ret
}

func validateWorkerSettings(ctx context.Context, opts *JobOptions) error {
	if opts.Zone != "" && opts.WorkerRegion != "" {
		return errors.New("cannot use option zone with workerRegion; prefer either workerZone or workerRegion")
	}
	if opts.Zone != "" && opts.WorkerZone != "" {
		return errors.New("cannot use option zone with workerZone; prefer workerZone")
	}
	if opts.WorkerZone != "" && opts.WorkerRegion != "" {
		return errors.New("workerRegion and workerZone options are mutually exclusive")
	}

	hasExperimentWorkerRegion := false
	for _, experiment := range opts.Experiments {
		if strings.HasPrefix(experiment, "worker_region") {
			hasExperimentWorkerRegion = true
			break
		}
	}

	if hasExperimentWorkerRegion && opts.WorkerRegion != "" {
		return errors.New("experiment worker_region and option workerRegion are mutually exclusive")
	}
	if hasExperimentWorkerRegion && opts.WorkerZone != "" {
		return errors.New("experiment worker_region and option workerZone are mutually exclusive")

View on GitHub (pinned to 12126d8942)