{"record":{"id":"da6cfeea49256fff","repo":"apache/beam","slug":"documented-config-should-set-only-one-of-ignored-or","errorCode":null,"errorMessage":"Documented config should set only one of 'ignored' or 'documented'. Check _DOCUMENTED_MANAGED_CONFIGS","messagePattern":"Documented config should set only one of 'ignored' or 'documented'\\. Check _DOCUMENTED_MANAGED_CONFIGS","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"sdks/python/gen_managed_doc.py","lineNumber":297,"sourceCode":"  else:\n    return field_name\n\n\ndef resolve_field_name(config_aliases: dict, field_name: str) -> str:\n  public_name = next((k for k, v in config_aliases.items() if v == field_name),\n                     field_name)\n  return public_name\n\n\ndef should_document(public_config: dict, field_name: str) -> bool:\n  if not public_config:\n    return True\n\n  ignored = public_config.get(\"ignored\", [])\n  documented = public_config.get(\"available\", [])\n\n  if not ignored and not documented:\n    raise RuntimeError(\n        \"Documented config should set only one of 'ignored' or 'documented'. \"\n        \"Check \" + _DOCUMENTED_MANAGED_CONFIGS)\n  if documented:\n    return field_name in documented\n  else:  # ignored\n    return field_name not in ignored\n\n\ndef spaces(n: int):\n  return \" \" * n\n\n\ndef get_type_color(primitive_type: str):\n  if primitive_type == \"str\":\n    return \"green\"\n  elif primitive_type.startswith(\"int\"):\n    return \"#f54251\"\n  elif primitive_type == \"boolean\":","sourceCodeStart":279,"sourceCodeEnd":315,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/gen_managed_doc.py#L279-L315","documentation":"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.","triggerScenarios":"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.","commonSituations":"Contributors adding a new managed config forget to fill in the ignored/available lists; refactoring the manifest leaves an entry empty.","solutions":["Open _DOCUMENTED_MANAGED_CONFIGS in gen_managed_doc.py and give the offending field entry either an 'available' list or an 'ignored' list.","Prefer 'ignored' to document everything except listed fields.","Re-run gen_managed_doc.py to confirm generation completes."],"exampleFix":"// before\n'KafkaReadConfig': {'public_config': {}}\n// after\n'KafkaReadConfig': {'public_config': {'ignored': ['bootstrap_servers']}}","handlingStrategy":"validation","validationCode":"pc = entry.get('public_config', {})\nassert bool(pc.get('ignored')) != bool(pc.get('available')), \\\n    \"set exactly one of 'ignored' or 'available'\"","typeGuard":"def has_valid_inclusion_rule(cfg):\n    return bool(cfg.get('ignored')) or bool(cfg.get('available'))","tryCatchPattern":"try:\n    generate_managed_doc()\nexcept RuntimeError as e:\n    if \"'ignored' or 'documented'\" in str(e):\n        print('Fill in ignored/available for the offending config entry')","preventionTips":["Add a unit test asserting every manifest entry sets exactly one list.","Copy an existing manifest entry as a template when adding new configs.","Review manifest diffs for empty public_config blocks."],"tags":["code-generation","docs","config","apache-beam"],"backgroundTag":"conflicting-config-options","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"}