apache/beam · error · RuntimeError

unknown artifact type

Error message

unknown artifact type: %s

What it means

Stager.extract_staging_tuple_iter only supports artifact type_urn FILE (urllib or file type). When an artifact's type_urn is anything else, the Python stager cannot stage it and raises RuntimeError listing the unsupported type URN — the sibling check to the unknown-role error just above it in the same loop.

Solutions

1. Check the reported type_urn and remove/replace that artifact with a standard FILE artifact.
2. Align Beam versions across SDK, stager, and runner so artifact type sets match.
3. If you author the artifacts, emit type_urn FILE with proper role payloads instead of custom types.
4. File/consult Beam issue tracker if a legitimate new artifact type is being rejected — may need a stager update.

Example fix

// before
artifact = beam_runner_api_pb2.Artifact(type_urn='beam:artifact:type:unknown:v1', ...)
// after
artifact = beam_runner_api_pb2.Artifact(type_urn=common_urns.artifact_types.FILE.urn, ...)
artifact.role_urn = common_urns.artifact_roles.STAGED_FILE.urn

from apache_beam.portability.api import beam_runner_api_pb2
from apache_beam.runners.portability import common_urns
for a in artifacts:
    if a.type_urn != common_urns.artifact_types.FILE.urn:
        raise SystemExit(f'Unsupported artifact type: {a.type_urn}')

try:
    resources = Stager.create_and_stage_job_resources(options, tmpdir)
except RuntimeError as e:
    if e.args and e.args[0].startswith('unknown artifact type:'):
        fix_or_drop_artifact(e.args[0].split(': ', 1)[1])
    else:
        raise

When it happens

Trigger: An artifact list containing a non-FILE typed artifact (e.g. an embedded or future artifact type) is passed to create_job_resources/extract_staging_tuple_iter during job staging.

Common situations: Newer Beam SDK emitting new artifact types to an older stager; custom tooling constructing Artifact protos with experimental type URNs; corrupted or hand-written pipeline proto.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• unknown role type
• Cannot convert from nanoseconds to microseconds because…
• cannot encode a null ByteString
• Cannot interpret a request received over control channel…
• Cannot provide because is not a subclass of

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

Appendix: source

Thrown at sdks/python/apache_beam/runners/portability/stager.py:167

      artifacts: list[beam_runner_api_pb2.ArtifactInformation]):
    for artifact in artifacts:
      if artifact.type_urn == common_urns.artifact_types.FILE.urn:
        file_payload = beam_runner_api_pb2.ArtifactFilePayload()
        file_payload.ParseFromString(artifact.type_payload)
        src = file_payload.path
        sha256 = file_payload.sha256
        if artifact.role_urn == common_urns.artifact_roles.STAGING_TO.urn:
          role_payload = beam_runner_api_pb2.ArtifactStagingToRolePayload()
          role_payload.ParseFromString(artifact.role_payload)
          dst = role_payload.staged_name
        elif (artifact.role_urn ==
              common_urns.artifact_roles.PIP_REQUIREMENTS_FILE.urn):
          dst = hashlib.sha256(artifact.SerializeToString()).hexdigest()
        else:
          raise RuntimeError("unknown role type: %s" % artifact.role_urn)
        yield (src, dst, sha256)
      else:
        raise RuntimeError("unknown artifact type: %s" % artifact.type_urn)

  @staticmethod
  def create_job_resources(
      options: PipelineOptions,
      temp_dir: str,
      build_setup_args: Optional[list[str]] = None,
      pypi_requirements: Optional[list[str]] = None,
      populate_requirements_cache: Optional[Callable[[str, str, bool],
                                                     None]] = None,
      skip_prestaged_dependencies: Optional[bool] = False,
      log_submission_env_dependencies: Optional[bool] = True,
  ):
    """For internal use only; no backwards-compatibility guarantees.

        Creates (if needed) a list of job resources.

        Args:
          options: Command line options. More specifically the function will

View on GitHub (pinned to 12126d8942)