{"record":{"id":"f21a82e11b4bd6dd","repo":"apache/beam","slug":"could-not-translate-the-internal-step-name-r","errorCode":null,"errorMessage":"Could not translate the internal step name %r.","messagePattern":"Could not translate the internal step name %r\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"warning","filePath":"sdks/python/apache_beam/runners/dataflow/dataflow_metrics.py","lineNumber":118,"sourceCode":"          'Could not translate the internal step name %r since job graph is '\n          'not available.' % internal_name)\n    user_step_name = None\n    if (self._job_graph and internal_name\n        in self._job_graph.proto_pipeline.components.transforms.keys()):\n      # Dataflow Portable Runner with portable job submission uses proto transform map\n      # IDs for step names. Also PTransform.unique_name maps to user step names.\n      # Hence we lookup user step names based on the proto.\n      user_step_name = self._job_graph.proto_pipeline.components.transforms[\n          internal_name].unique_name\n    else:\n      try:\n        step = _get_match(\n            self._job_graph.proto.steps, lambda x: x.name == internal_name)\n        user_step_name = step.properties.get('user_name')\n      except ValueError:\n        pass  # Exception is handled below.\n    if not user_step_name:\n      raise ValueError(\n          'Could not translate the internal step name %r.' % internal_name)\n    return user_step_name\n\n  def _get_metric_key(self, metric):\n    \"\"\"Populate the MetricKey object for a queried metric result.\"\"\"\n    step = \"\"\n    name = metric.name.name  # Always extract a name\n    labels = {}\n    try:  # Try to extract the user step name.\n      # If ValueError is thrown within this try-block, it is because of\n      # one of the following:\n      # 1. Unable to translate the step name. Only happening with improperly\n      #   formatted job graph (unlikely), or step name not being the internal\n      #   step name (only happens for unstructured-named metrics).\n      # 2. Unable to unpack [step] or [namespace]; which should only happen\n      #   for unstructured names.\n      step = metric.name.context['step']\n      step = self._translate_step_name(step)","sourceCodeStart":100,"sourceCodeEnd":136,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/runners/dataflow/dataflow_metrics.py#L100-L136","documentation":"After consulting both the proto transform map and job proto steps, if no user step name was found for the internal step name, DataflowMetrics raises ValueError('Could not translate the internal step name %r.').","triggerScenarios":"Querying a metric whose internal step name exists neither in job_graph.proto_pipeline.components.transforms nor as a step name in job_graph.proto.steps (or the step lacks a 'user_name' property).","commonSituations":"Job graph and metrics out of sync: querying metrics from an updated/relaunched job using an older graph, or system steps without user_name labels.","solutions":["Wrap metric queries in try/except ValueError and skip or label untranslatable steps.","Make sure the job graph belongs to the same job (same job_id/revision) as the metrics.","Filter out system/internal metrics before translation."],"exampleFix":"# before\nfor key in result.keys():\n    user_name = metrics._translate_step_name(key.step)\n# after\nfor key in result.keys():\n    try:\n        user_name = metrics._translate_step_name(key.step)\n    except ValueError:\n        user_name = key.step  # keep internal name","handlingStrategy":"try-catch","validationCode":"known = set(job_graph.proto_pipeline.components.transforms) | {s.name for s in job_graph.proto.steps}\nif internal_name not in known:\n    skip_translation(internal_name)","typeGuard":null,"tryCatchPattern":"try:\n    user_name = metrics._translate_step_name(internal_name)\nexcept ValueError:\n    user_name = internal_name  # untranslated internal step","preventionTips":["Keep job graph and metrics from the same job revision.","Skip system-generated steps lacking user_name labels.","Never assume every internal step name resolves."],"tags":["python","apache-beam","dataflow","metrics"],"backgroundTag":"record-not-found","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}