apache/beam · error · ValueError

f"When using include, it must be the only parameter: {provid

Error message

f"When using include, it must be the only parameter: {provider_spec} at {source_path}:{SafeLineLoader.get_line(provider_spec)}"

What it means

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.

Source

Thrown at sdks/python/apache_beam/yaml/yaml_provider.py:1663

def load_providers(source_path: str) -> Iterable[Provider]:
  from apache_beam.yaml.yaml_transform import SafeLineLoader
  provider_specs = yaml.load(
      _read_url_or_filepath(source_path), Loader=SafeLineLoader)
  if not isinstance(provider_specs, list):
    raise ValueError(f"Provider file {source_path} must be a list of Providers")
  return parse_providers(source_path, provider_specs)


@_as_list
def parse_providers(source_path,
                    provider_specs: Iterable[Mapping]) -> Iterable[Provider]:
  from apache_beam.yaml.yaml_transform import SafeLineLoader
  for provider_spec in provider_specs:
    if 'include' in provider_spec:
      if len(SafeLineLoader.strip_metadata(provider_spec)) != 1:
        raise ValueError(
            f"When using include, it must be the only parameter: "
            f"{provider_spec} "
            f"at {source_path}:{SafeLineLoader.get_line(provider_spec)}")
      include_path = _join_url_or_filepath(
          source_path, provider_spec['include'])
      try:
        yield from load_providers(include_path)

      except Exception as exn:
        raise ValueError(
            f"Error loading providers from {include_path} included at "
            f"{source_path}:{SafeLineLoader.get_line(provider_spec)}\n" +
            str(exn)) from exn
    else:
      yield ExternalProvider.provider_from_spec(source_path, provider_spec)


def merge_providers(*provider_sets) -> Mapping[str, Iterable[Provider]]:

View on GitHub (pinned to 12126d8942)

Solutions

1. Make the include entry contain exactly one key: {'include': 'path.yaml'}.
2. Move any extra parameters into the included file's own provider specs.
3. If intending to define a provider, remove the 'include' key and specify type/config directly.

Example fix

# before
- include: extra_providers.yaml
  type: Sql

# after
- include: extra_providers.yaml

for entry in provider_specs:
    if 'include' in entry and len(entry) != 1:
        raise ValueError(f'include entry must have exactly one key: {entry}')

def is_pure_include(entry: dict) -> bool:
    return set(entry.keys()) == {'include'}

try:
    providers = list(parse_providers(path, specs))
except ValueError as e:
    logging.error('Invalid provider spec: %s', e)
    raise

When it happens

Trigger: A provider list entry like {'include': 'more_providers.yaml', 'type': 'Sql'} — i.e. 'include' combined with 'type', 'config', 'name', or any other key.

Common situations: Users add metadata (name, description) to an include entry, or copy a provider spec and append an include path to it.

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

• f"Provider file {source_path} must be a list of Providers"
• f"Error loading providers from {include_path} included at {s
• Node ID cannot be empty
• Edge source and target cannot be empty
• Invalid feature store yaml file provided. Make sure the %s c

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