apache/beam · error · ValueError

Input must be a string.

Error message

Input must be a string.

What it means

ResourceHint._parse_str is the shared parser for string-valued resource hints (e.g. min_ram or accelerator hints); the value being parsed is not a str, so it cannot be interpreted as a hint value from pipeline options.

Solutions

1. Convert the value to str before setting it: `options.view_as(...).hint_name = str(value)`.
2. Use the correct parser for the value type (e.g. `_parse_int` for numbers, `_parse_storage_size_str` for sizes like '2GiB').
3. If your hint values come from config files, coerce loaded values with `str()` or JSON-schema validation at load time.

Example fix

# before
hints = {'accelerator': 4}
# after
hints = {'accelerator': str(4)}

if not isinstance(v, str):
  raise TypeError('hint value must be str')

def is_str(v):
  return isinstance(v, str)

try:
  parsed = ResourceHint._parse_str(value)
except ValueError as e:
  log.error('Bad hint value %r: %s', value, e)
  parsed = ResourceHint._parse_str(str(value))

When it happens

Trigger: Declaring a resource hint whose parser is _parse_str with a non-string value, e.g. `@ResourceHint(urn=..., parser=ResourceHint._parse_str)` used with a hint value given as an int, bytes, or None in the pipeline options.

Common situations: Passing numeric hint values (e.g. minimum_ram_number as int when a string parser is expected), YAML/JSON config loading that produces non-str types, typos in option names routing values to the wrong parser.

Related errors

• Input must be a string or integer.
• Input must be an integer.
• An unsupported sink was specified
• At least one of --render_port or --render_output must be…
• buffer_sec must be >= 0, got

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

Appendix: source

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

  @staticmethod
  def get_by_name(name):
    return ResourceHint._name_to_known_hints[name]

  @staticmethod
  def is_registered(name):
    return name in ResourceHint._name_to_known_hints

  @staticmethod
  def register_resource_hint(hint_name: str, hint_class: type) -> None:
    assert issubclass(hint_class, ResourceHint)
    assert hint_class.urn is not None
    ResourceHint._name_to_known_hints[hint_name] = hint_class
    ResourceHint._urn_to_known_hints[hint_class.urn] = hint_class

  @staticmethod
  def _parse_str(value):
    if not isinstance(value, str):
      raise ValueError("Input must be a string.")
    return value.encode('ascii')

  @staticmethod
  def _parse_int(value):
    if isinstance(value, str):
      value = int(value)
    if not isinstance(value, int):
      raise ValueError("Input must be an integer.")
    return str(value).encode('ascii')

  @staticmethod
  def _parse_storage_size_str(value):
    """Parses a human-friendly storage size string into a number of bytes.
    """
    if isinstance(value, int):
      return ResourceHint._parse_int(value)

    if not isinstance(value, str):

View on GitHub (pinned to 12126d8942)