{"record":{"id":"4a63624dd86d7aa9","repo":"apache/beam","slug":"clusters-in-the-global-region-are-not-supported","errorCode":null,"errorMessage":"Clusters in the global region are not supported.","messagePattern":"Clusters in the global region are not supported\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/runners/interactive/interactive_beam.py","lineNumber":443,"sourceCode":"  def create(\n      self, cluster_identifier: ClusterIdentifier) -> DataprocClusterManager:\n    \"\"\"Creates a Dataproc cluster manager provisioned for the cluster\n    identified. If the cluster is known, returns an existing cluster manager.\n    \"\"\"\n    # Try to get some not-None cluster metadata.\n    cluster_metadata = self.cluster_metadata(cluster_identifier)\n    if not cluster_metadata:\n      raise ValueError(\n          'Unknown cluster identifier: %s. Cannot create or reuse'\n          'a Dataproc cluster.')\n    if not cluster_metadata.region:\n      _LOGGER.info(\n          'No region information was detected, defaulting Dataproc cluster '\n          'region to: us-central1.')\n      cluster_metadata.region = 'us-central1'\n    elif cluster_metadata.region == 'global':\n      # The global region is unsupported as it will be eventually deprecated.\n      raise ValueError('Clusters in the global region are not supported.')\n    # else use the provided region.\n    if (cluster_metadata.num_workers and\n        cluster_metadata.num_workers < self.DATAPROC_MINIMUM_WORKER_NUM):\n      _LOGGER.info(\n          'At least %s workers are required for a cluster, defaulting to %s.',\n          self.DATAPROC_MINIMUM_WORKER_NUM,\n          self.DATAPROC_MINIMUM_WORKER_NUM)\n      cluster_metadata.num_workers = self.DATAPROC_MINIMUM_WORKER_NUM\n    known_dcm = self.dataproc_cluster_managers.get(cluster_metadata, None)\n    if known_dcm:\n      return known_dcm\n    dcm = DataprocClusterManager(cluster_metadata)\n    dcm.create_flink_cluster()\n    # ClusterMetadata with derivative fields populated by the dcm.\n    derived_meta = dcm.cluster_metadata\n    self.dataproc_cluster_managers[derived_meta] = dcm\n    self.master_urls[derived_meta.master_url] = derived_meta\n    # Update the default cluster metadata to the one just created.","sourceCodeStart":425,"sourceCodeEnd":461,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/runners/interactive/interactive_beam.py#L425-L461","documentation":"DataprocClusterManager.create() rejects clusters whose region is 'global', raising this ValueError. Google is deprecating the Dataproc global region, so Beam's interactive runner explicitly refuses to provision clusters there instead of defaulting to a concrete region.","triggerScenarios":"Calling create() with ClusterMetadata whose region == 'global' (or the interactive option/DPZ config resolving to 'global'), e.g. metadata derived from an old configuration or an environment where region defaults to 'global'.","commonSituations":"Legacy Dataproc configs that used region 'global'; gcloud default region unset so code paths fill 'global'; migrating older notebooks to newer Beam where regional clusters are mandatory.","solutions":["Set an explicit region (e.g. 'us-central1') in ClusterMetadata instead of 'global'.","Configure the region via the interactive environment option (cluster region) or GOOGLE_CLOUD_DATAPROC_REGION appropriately.","Migrate any existing 'global' Dataproc clusters to a regional endpoint; recreate the cluster regionally.","Update gcloud config: gcloud config set dataproc/region us-central1 so defaults stop yielding 'global'."],"exampleFix":"// before\nmetadata = ClusterMetadata(cluster_name='c1', project_id='proj', region='global')\nmanager = ClustersManager.create(cluster_identifier=metadata)\n// after\nmetadata = ClusterMetadata(cluster_name='c1', project_id='proj', region='us-central1')\nmanager = ClustersManager.create(cluster_identifier=metadata)","handlingStrategy":"validation","validationCode":"metadata = ClusterMetadata(cluster_name=name, project_id=project, region=region)\nassert metadata.region != 'global', 'Dataproc global region is unsupported; pick a regional endpoint'","typeGuard":"def region_is_supported(region: str) -> bool:\n    return bool(region) and region != 'global'","tryCatchPattern":"try:\n    manager = ClustersManager.create(cluster_identifier=metadata)\nexcept ValueError as e:\n    if 'global region' in str(e):\n        metadata.region = 'us-central1'\n        manager = ClustersManager.create(cluster_identifier=metadata)\n    else:\n        raise","preventionTips":["Always set an explicit regional value (e.g. us-central1) in ClusterMetadata","Update gcloud config: gcloud config set dataproc/region <region>","Migrate legacy 'global' Dataproc clusters to a region","Scrub configs/scripts that still hardcode region 'global'"],"tags":["gcp","dataproc","deprecation","python"],"backgroundTag":"deprecated-api-usage","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"}