{"record":{"id":"78c72cf96477a894","repo":"apache/beam","slug":"unable-to-import-vertexaimodelhandlerjson-please-install-gcp","errorCode":null,"errorMessage":"Unable to import VertexAIModelHandlerJSON. Please install gcp dependencies: `pip install apache_beam[gcp]`","messagePattern":"Unable to import VertexAIModelHandlerJSON\\. Please install gcp dependencies: `pip install apache_beam\\[gcp\\]`","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/yaml/yaml_ml.py","lineNumber":258,"sourceCode":"      invoke_route: The custom route path to use when invoking\n        endpoints with arbitrary prediction routes. When specified, uses\n        `Endpoint.invoke()` instead of `Endpoint.predict()`. The route\n        should start with a forward slash, e.g., \"/predict/v1\".\n        See\n        https://cloud.google.com/vertex-ai/docs/predictions/use-arbitrary-custom-routes\n        for more information.\n      min_batch_size: The minimum batch size to use when batching\n        inputs.\n      max_batch_size: The maximum batch size to use when batching\n        inputs.\n      max_batch_duration_secs: The maximum amount of time to buffer\n        a batch before emitting; used in streaming contexts.\n    \"\"\"\n\n    try:\n      from apache_beam.ml.inference.vertex_ai_inference import VertexAIModelHandlerJSON\n    except ImportError:\n      raise ValueError(\n          'Unable to import VertexAIModelHandlerJSON. Please '\n          'install gcp dependencies: `pip install apache_beam[gcp]`')\n\n    _handler = VertexAIModelHandlerJSON(\n        endpoint_id=str(endpoint_id),\n        project=project,\n        location=location,\n        experiment=experiment,\n        network=network,\n        private=private,\n        invoke_route=invoke_route,\n        min_batch_size=min_batch_size,\n        max_batch_size=max_batch_size,\n        max_batch_duration_secs=max_batch_duration_secs)\n\n    super().__init__(_handler, preprocess, postprocess)\n\n  @staticmethod","sourceCodeStart":240,"sourceCodeEnd":276,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/yaml/yaml_ml.py#L240-L276","documentation":"Raised when the Vertex AI handler class VertexAIModelHandlerJSON cannot be imported because the GCP extra dependencies of apache_beam are not installed. yaml_ml imports the handler lazily inside __init__ and converts the ImportError into a ValueError with install instructions.","triggerScenarios":"Using the YAML RunInference ML transform with a Vertex AI model handler (type VertexAI / vertex_ai_model_handler_json) on an environment where apache_beam was installed without the [gcp] extra, so google-cloud-aiplatform and related packages are absent.","commonSituations":"Deploying a Beam YAML pipeline to an environment with only the base apache_beam package; using --extra-package or requirements files that omit gcp extras; running in containers built from plain apache_beam images.","solutions":["Install GCP extras: pip install apache_beam[gcp]","Ensure the runtime (Dataflow container, cluster worker, Flink/Kubernetes image) has the same extras installed","If you don't need Vertex AI, switch the model handler type to a local or other supported handler"],"exampleFix":"# before\npip install apache_beam\n# after\npip install 'apache_beam[gcp]'","handlingStrategy":"try-catch","validationCode":"try:\n    from apache_beam.ml.inference.vertex_ai_inference import VertexAIModelHandlerJSON\nexcept ImportError:\n    raise SystemExit(\"Run: pip install 'apache_beam[gcp]'\")","typeGuard":"def has_vertex_ai_handler():\n    import importlib.util\n    return importlib.util.find_spec('apache_beam.ml.inference.vertex_ai_inference') is not None","tryCatchPattern":"try:\n    transform = RunInference(model_handler=handler_spec)\nexcept ValueError as e:\n    if 'install gcp dependencies' in str(e):\n        install_gcp_extras()\n    else:\n        raise","preventionTips":["Install apache_beam[gcp] in every environment that runs the pipeline","Pin extras in requirements.txt: apache_beam[gcp]==<version>","Smoke-test the import in worker images before deploying"],"tags":["python","apache-beam","dependency","gcp","vertex-ai"],"backgroundTag":"missing-optional-dependency","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}