{"record":{"id":"72c01487a2838d98","repo":"apache/beam","slug":"f-when-using-include-it-must-be-the-only-parameter-provider","errorCode":null,"errorMessage":"f\"When using include, it must be the only parameter: {provider_spec} at {source_path}:{SafeLineLoader.get_line(provider_spec)}\"","messagePattern":"f\"When using include, it must be the only parameter: (.+?) at (.+?):(.+?)\"","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/yaml/yaml_provider.py","lineNumber":1663,"sourceCode":"\n\ndef load_providers(source_path: str) -> Iterable[Provider]:\n  from apache_beam.yaml.yaml_transform import SafeLineLoader\n  provider_specs = yaml.load(\n      _read_url_or_filepath(source_path), Loader=SafeLineLoader)\n  if not isinstance(provider_specs, list):\n    raise ValueError(f\"Provider file {source_path} must be a list of Providers\")\n  return parse_providers(source_path, provider_specs)\n\n\n@_as_list\ndef parse_providers(source_path,\n                    provider_specs: Iterable[Mapping]) -> Iterable[Provider]:\n  from apache_beam.yaml.yaml_transform import SafeLineLoader\n  for provider_spec in provider_specs:\n    if 'include' in provider_spec:\n      if len(SafeLineLoader.strip_metadata(provider_spec)) != 1:\n        raise ValueError(\n            f\"When using include, it must be the only parameter: \"\n            f\"{provider_spec} \"\n            f\"at {source_path}:{SafeLineLoader.get_line(provider_spec)}\")\n      include_path = _join_url_or_filepath(\n          source_path, provider_spec['include'])\n      try:\n        yield from load_providers(include_path)\n\n      except Exception as exn:\n        raise ValueError(\n            f\"Error loading providers from {include_path} included at \"\n            f\"{source_path}:{SafeLineLoader.get_line(provider_spec)}\\n\" +\n            str(exn)) from exn\n    else:\n      yield ExternalProvider.provider_from_spec(source_path, provider_spec)\n\n\ndef merge_providers(*provider_sets) -> Mapping[str, Iterable[Provider]]:","sourceCodeStart":1645,"sourceCodeEnd":1681,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/yaml/yaml_provider.py#L1645-L1681","documentation":"In parse_providers, a provider spec containing the 'include' key must contain no other keys — include is a file-inclusion directive, not a provider. If 'include' appears alongside other parameters, a ValueError is raised.","triggerScenarios":"A provider list entry like {'include': 'more_providers.yaml', 'type': 'Sql'} — i.e. 'include' combined with 'type', 'config', 'name', or any other key.","commonSituations":"Users add metadata (name, description) to an include entry, or copy a provider spec and append an include path to it.","solutions":["Make the include entry contain exactly one key: {'include': 'path.yaml'}.","Move any extra parameters into the included file's own provider specs.","If intending to define a provider, remove the 'include' key and specify type/config directly."],"exampleFix":"# before\n- include: extra_providers.yaml\n  type: Sql\n\n# after\n- include: extra_providers.yaml","handlingStrategy":"validation","validationCode":"for entry in provider_specs:\n    if 'include' in entry and len(entry) != 1:\n        raise ValueError(f'include entry must have exactly one key: {entry}')","typeGuard":"def is_pure_include(entry: dict) -> bool:\n    return set(entry.keys()) == {'include'}","tryCatchPattern":"try:\n    providers = list(parse_providers(path, specs))\nexcept ValueError as e:\n    logging.error('Invalid provider spec: %s', e)\n    raise","preventionTips":["Never mix 'include' with other keys in a provider entry","Keep metadata out of include directives","Code-review provider YAML for single-key include entries"],"tags":["yaml","python","apache-beam","provider-config"],"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-14T21:17:11.552Z"}