apache/beam · error · RuntimeError

Documented config should set only one of 'ignored' or…

Error message

Documented config should set only one of 'ignored' or 'documented'. Check _DOCUMENTED_MANAGED_CONFIGS

What it means

gen_managed_doc.py's should_document requires each field entry in the documented managed-config manifest (_DOCUMENTED_MANAGED_CONFIGS) to express inclusion via exactly one of 'ignored' or 'available' lists. If a public_config block has neither (both empty/absent), the inclusion rule is ambiguous, so generation aborts with RuntimeError.

Solutions

1. Open _DOCUMENTED_MANAGED_CONFIGS in gen_managed_doc.py and give the offending field entry either an 'available' list or an 'ignored' list.
2. Prefer 'ignored' to document everything except listed fields.
3. Re-run gen_managed_doc.py to confirm generation completes.

Example fix

// before
'KafkaReadConfig': {'public_config': {}}
// after
'KafkaReadConfig': {'public_config': {'ignored': ['bootstrap_servers']}}

pc = entry.get('public_config', {})
assert bool(pc.get('ignored')) != bool(pc.get('available')), \
    "set exactly one of 'ignored' or 'available'"

def has_valid_inclusion_rule(cfg):
    return bool(cfg.get('ignored')) or bool(cfg.get('available'))

try:
    generate_managed_doc()
except RuntimeError as e:
    if "'ignored' or 'documented'" in str(e):
        print('Fill in ignored/available for the offending config entry')

When it happens

Trigger: Running the managed-transform doc generator while a field's public_config dict in _DOCUMENTED_MANAGED_CONFIGS contains neither a non-empty 'ignored' nor 'available' list.

Common situations: Contributors adding a new managed config forget to fill in the ignored/available lists; refactoring the manifest leaves an entry empty.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Unsupported type
• buffer_sec must be >= 0, got
• "Cannot specify 'callable' with 'path' and 'name' for…
• Chain at missing transforms property.
• Encountered an error when retrieving a configuration

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

Appendix: source

Thrown at sdks/python/gen_managed_doc.py:297

  else:
    return field_name


def resolve_field_name(config_aliases: dict, field_name: str) -> str:
  public_name = next((k for k, v in config_aliases.items() if v == field_name),
                     field_name)
  return public_name


def should_document(public_config: dict, field_name: str) -> bool:
  if not public_config:
    return True

  ignored = public_config.get("ignored", [])
  documented = public_config.get("available", [])

  if not ignored and not documented:
    raise RuntimeError(
        "Documented config should set only one of 'ignored' or 'documented'. "
        "Check " + _DOCUMENTED_MANAGED_CONFIGS)
  if documented:
    return field_name in documented
  else:  # ignored
    return field_name not in ignored


def spaces(n: int):
  return " " * n


def get_type_color(primitive_type: str):
  if primitive_type == "str":
    return "green"
  elif primitive_type.startswith("int"):
    return "#f54251"
  elif primitive_type == "boolean":

View on GitHub (pinned to 12126d8942)