{"record":{"id":"45cb493c804c6316","repo":"apache/beam","slug":"unknown-resource-hint-hint","errorCode":null,"errorMessage":"Unknown resource hint: {hint}.","messagePattern":"Unknown resource hint: (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/transforms/resources.py","lineNumber":227,"sourceCode":"    'MaxActiveBundlesPerWorker', MaxActiveBundlesPerWorkerHint)\n# Alias for common typo.\nResourceHint.register_resource_hint(\n    'max_active_bundle_per_worker', MaxActiveBundlesPerWorkerHint)\nResourceHint.register_resource_hint(\n    'MaxActiveBundlePerWorker', MaxActiveBundlesPerWorkerHint)\n\n\ndef parse_resource_hints(hints: dict[Any, Any]) -> dict[str, bytes]:\n  parsed_hints = {}\n  for hint, value in hints.items():\n    try:\n      hint_cls = ResourceHint.get_by_name(hint)\n      try:\n        parsed_hints.update(hint_cls.parse(value))\n      except ValueError:\n        raise ValueError(f\"Resource hint {hint} has invalid value {value}.\")\n    except KeyError:\n      raise ValueError(f\"Unknown resource hint: {hint}.\")\n\n  return parsed_hints\n\n\ndef resource_hints_from_options(\n    options: Optional[PipelineOptions]) -> dict[str, bytes]:\n  if options is None:\n    return {}\n  hints = {}\n  option_specified_hints = options.view_as(StandardOptions).resource_hints\n\n  if isinstance(option_specified_hints, dict):\n    return parse_resource_hints(option_specified_hints)\n\n  for hint in option_specified_hints:\n    if '=' in hint:\n      k, v = hint.split('=', maxsplit=1)\n      hints[k] = v","sourceCodeStart":209,"sourceCodeEnd":245,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/transforms/resources.py#L209-L245","documentation":"ResourceHint.get_by_name raises KeyError for a hint name that has no registered ResourceHint subclass; parse_resource_hints converts that into this ValueError. Only hints registered via ResourceHint.register_resource_hint (or built-ins) are accepted.","triggerScenarios":"Passing --resource_hint=my_hint=value where 'my_hint' was never registered; misspelling a built-in hint name (e.g. 'ram_mb' vs 'min_ram_mb').","commonSituations":"Hints copied from a different runner's docs (runner-specific hints not present in this Beam install); custom hints whose registering module was never imported; renamed hints across Beam versions.","solutions":["Check the exact hint name against ResourceHint.get_registered_hint_names().","Import/register the custom hint class before constructing the pipeline (custom ResourceHint subclasses register on import).","Remove the unknown hint if it targets a runner you are not using."],"exampleFix":"// before\n--resource_hint=cpu_cores=4   # unknown name\n// after\n--resource_hint=min_ram_mb=8GB  # use a registered hint name","handlingStrategy":"validation","validationCode":"from apache_beam.transforms.resources import ResourceHint\nunknown = set(raw_hints) - set(ResourceHint.get_registered_hint_names())\nassert not unknown, f\"Unregistered resource hints: {unknown}\"","typeGuard":"def all_hints_known(hints: dict) -> bool:\n    from apache_beam.transforms.resources import ResourceHint\n    known = set(ResourceHint.get_registered_hint_names())\n    return all(h in known for h in hints)","tryCatchPattern":"try:\n    hints = parse_resource_hints(raw_hints)\nexcept ValueError as e:\n    if e.args and str(e).startswith('Unknown resource hint'):\n        log.warning('Dropping unknown hint: %s', e)\n        bad = str(e).rsplit(':', 1)[1].strip().rstrip('.')\n        hints = parse_resource_hints({k: v for k, v in raw_hints.items() if k != bad})\n    else:\n        raise","preventionTips":["List registered hints with ResourceHint.get_registered_hint_names() before authoring options.","Import the module defining custom hints before building the pipeline.","Verify hint names against the docs of the runner you actually target."],"tags":["python","apache-beam","resource-hints","unknown-key"],"backgroundTag":"resource-not-found","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}