apache/beam · error · ValueError

Unknown resource hint

Error message

Unknown resource hint: {hint}.

What it means

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.

Solutions

1. Check the exact hint name against ResourceHint.get_registered_hint_names().
2. Import/register the custom hint class before constructing the pipeline (custom ResourceHint subclasses register on import).
3. Remove the unknown hint if it targets a runner you are not using.

Example fix

// before
--resource_hint=cpu_cores=4   # unknown name
// after
--resource_hint=min_ram_mb=8GB  # use a registered hint name

from apache_beam.transforms.resources import ResourceHint
unknown = set(raw_hints) - set(ResourceHint.get_registered_hint_names())
assert not unknown, f"Unregistered resource hints: {unknown}"

def all_hints_known(hints: dict) -> bool:
    from apache_beam.transforms.resources import ResourceHint
    known = set(ResourceHint.get_registered_hint_names())
    return all(h in known for h in hints)

try:
    hints = parse_resource_hints(raw_hints)
except ValueError as e:
    if e.args and str(e).startswith('Unknown resource hint'):
        log.warning('Dropping unknown hint: %s', e)
        bad = str(e).rsplit(':', 1)[1].strip().rstrip('.')
        hints = parse_resource_hints({k: v for k, v in raw_hints.items() if k != bad})
    else:
        raise

When it happens

Trigger: 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').

Common situations: 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.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Input must be a string.
• Input must be a string or integer.
• Input must be an integer.
• Invalid model update
• Resource hint has invalid value .

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

Appendix: source

Thrown at sdks/python/apache_beam/transforms/resources.py:227

    'MaxActiveBundlesPerWorker', MaxActiveBundlesPerWorkerHint)
# Alias for common typo.
ResourceHint.register_resource_hint(
    'max_active_bundle_per_worker', MaxActiveBundlesPerWorkerHint)
ResourceHint.register_resource_hint(
    'MaxActiveBundlePerWorker', MaxActiveBundlesPerWorkerHint)


def parse_resource_hints(hints: dict[Any, Any]) -> dict[str, bytes]:
  parsed_hints = {}
  for hint, value in hints.items():
    try:
      hint_cls = ResourceHint.get_by_name(hint)
      try:
        parsed_hints.update(hint_cls.parse(value))
      except ValueError:
        raise ValueError(f"Resource hint {hint} has invalid value {value}.")
    except KeyError:
      raise ValueError(f"Unknown resource hint: {hint}.")

  return parsed_hints


def resource_hints_from_options(
    options: Optional[PipelineOptions]) -> dict[str, bytes]:
  if options is None:
    return {}
  hints = {}
  option_specified_hints = options.view_as(StandardOptions).resource_hints

  if isinstance(option_specified_hints, dict):
    return parse_resource_hints(option_specified_hints)

  for hint in option_specified_hints:
    if '=' in hint:
      k, v = hint.split('=', maxsplit=1)
      hints[k] = v

View on GitHub (pinned to 12126d8942)