apache/beam · error · RuntimeError

unsupported artifact type

Error message

unsupported artifact type %s

What it means

While staging pipeline resources, _stage_resources encountered an artifact whose type it does not know how to stage (only known kinds like PYTHON, JAVA, or file artifacts are handled); the offending artifact type is interpolated into the message.

Solutions

1. Ensure all environment dependencies use artifact type FILE (beam:artifact:type:file:v1)
2. Regenerate/upgrade the expansion service so cross-language deps are materialized as files
3. Inspect pipeline.components.environments[].dependencies to find the offending dependency and remove or convert it

Example fix

# before
dep = beam_runner_api_pb2.ArtifactInformation(
    type_urn='beam:artifact:type:url:v1', ...)
# after
dep = beam_runner_api_pb2.ArtifactInformation(
    type_urn='beam:artifact:type:file:v1',
    type_payload=proto_utils.to_Bytes(
        beam_runner_api_pb2.ArtifactFilePayload(path='/local/file.jar')))

from apache_beam.portability import common_urns
for env in pipeline.proto.components.environments.values():
    for dep in env.dependencies:
        assert dep.type_urn == common_urns.artifact_types.FILE.urn, dep.type_urn

try:
    job = Job(pipeline, options)
except RuntimeError as e:
    if 'unsupported artifact type' in str(e):
        print('Non-file artifact dependency; fix expansion service or pipeline proto')
    raise

When it happens

Trigger: A pipeline environment carries dependencies typed as something other than FILE (e.g. from cross-language expansion services emitting non-file artifact types, or hand-built pipeline protos with custom artifact types).

Common situations: Cross-language pipelines where the foreign SDK expansion produces artifact dependencies Dataflow staging cannot handle; custom Beam environments constructed programmatically.

Related errors

• Dataflow can only execute pipeline steps in Docker…
• failed to open file
• The --staging_location option must be specified.
• unknown artifact type
• unknown role type

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

Appendix: source

Thrown at sdks/python/apache_beam/runners/dataflow/internal/apiclient.py:613

    total_size = os.path.getsize(from_path)
    self.stage_file_with_retry(
        to_folder, to_name, from_path, total_size=total_size)

  def _stage_resources(self, pipeline, options):
    google_cloud_options = options.view_as(GoogleCloudOptions)
    if google_cloud_options.staging_location is None:
      raise RuntimeError('The --staging_location option must be specified.')
    if google_cloud_options.temp_location is None:
      raise RuntimeError('The --temp_location option must be specified.')

    resources = []
    staged_paths = {}
    staged_hashes = {}
    for _, env in sorted(pipeline.components.environments.items(),
                         key=lambda kv: kv[0]):
      for dep in env.dependencies:
        if dep.type_urn != common_urns.artifact_types.FILE.urn:
          raise RuntimeError('unsupported artifact type %s' % dep.type_urn)
        type_payload = beam_runner_api_pb2.ArtifactFilePayload.FromString(
            dep.type_payload)

        if dep.role_urn == common_urns.artifact_roles.STAGING_TO.urn:
          remote_name = (
              beam_runner_api_pb2.ArtifactStagingToRolePayload.FromString(
                  dep.role_payload)).staged_name
          is_staged_role = True
        else:
          remote_name = os.path.basename(type_payload.path)
          is_staged_role = False
        # compute sha256 even if caching is disabled.
        # This is used to check the payload integrity along with caching.
        if not type_payload.sha256:
          type_payload.sha256 = self._compute_sha256(type_payload.path)

        if type_payload.sha256 and type_payload.sha256 in staged_hashes:
          _LOGGER.info(

View on GitHub (pinned to 12126d8942)