apache/beam · error · RuntimeError

unknown role type

Error message

unknown role type: %s

What it means

While building the staging resources for a portable job, Stager.extract_staging_tuple_iter maps each artifact's role URN to a destination name (STAGED_FILE uses role_payload.staged_name, PIP_REQUIREMENTS_FILE uses a hash). Any other role URN is unsupported by the Python stager and raises RuntimeError with the raw URN.

Solutions

1. Identify the offending role_urn from the error message and remove or convert that artifact at the source.
2. Upgrade apache-beam on the submitting side so both SDK and stager agree on known role URNs.
3. If it is your extension emitting the role, stage the artifact via a supported role (STAGED_FILE with role_payload.staged_name).
4. Check for mixed Beam versions between the job submission components (Runner harness vs stager).

Example fix

// before
artifact.role_urn = common_urns.artifact_roles.OTHER_ROLE.urn  # unsupported
// after
role_payload = beam_runner_api_pb2.ArtifactStagingToTargetPayload()
role_payload.staged_name = 'my_staged_file.txt'
artifact.role_urn = common_urns.artifact_roles.STAGED_FILE.urn
artifact.role_payload = role_payload.SerializeToString()

from apache_beam.runners.portability import common_urns
for a in artifacts:
    if a.role_urn not in {
        common_urns.artifact_roles.STAGED_FILE.urn,
        common_urns.artifact_roles.PIP_REQUIREMENTS_FILE.urn,
    }:
        raise SystemExit(f'Unsupported artifact role: {a.role_urn}')

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

When it happens

Trigger: An artifact with a role URN other than STAGED_FILE or PIP_REQUIREMENTS_FILE arrives in the artifact list — e.g. a runner/SDK or custom pipeline emits new role types the Python stager does not know.

Common situations: Custom artifact roles injected by an extension or internal pipeline; SDK/runner version mismatch where a newer role URN is sent to an older Python stager; hand-crafted RunnerAPI protos in tests or tooling.

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 artifact 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/11496dec42b2d103. Report an issue: GitHub.

Appendix: source

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

  @staticmethod
  def extract_staging_tuple_iter(
      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.

View on GitHub (pinned to 12126d8942)