apache/beam · error · ValueError

Unable to instantiate provider of type {type} at line {SafeL

Error message

Unable to instantiate provider of type {type} at line {SafeLineLoader.get_line(spec)}: {exn}

What it means

After passing validation, provider_from_spec calls the registered constructor as constructor(urns, **config). Any exception raised there is re-raised as a ValueError 'Unable to instantiate provider of type ... at line ...' with the original exception chained (from exn), so the underlying cause appears in the traceback.

Source

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

        'transforms', 'type', 'config'
    }
    if extra_params:
      raise ValueError(
          f'Unexpected parameters in provider of type {type} '
          f'at line {SafeLineLoader.get_line(spec)}: {extra_params}')
    if config.get('version', None) == 'BEAM_VERSION':
      config['version'] = beam_version
    if type in cls._provider_types:
      try:
        constructor = cls._provider_types[type]
        if 'provider_base_path' in inspect.signature(constructor).parameters:
          config['provider_base_path'] = source_path
        result = constructor(urns, **config)
        if not hasattr(result, 'to_json'):
          result.to_json = lambda: spec
        return result
      except Exception as exn:
        raise ValueError(
            f'Unable to instantiate provider of type {type} '
            f'at line {SafeLineLoader.get_line(spec)}: {exn}') from exn
    else:
      raise NotImplementedError(
          f'Unknown provider type: {type} '
          f'at line {SafeLineLoader.get_line(spec)}.')

  @classmethod
  def register_provider_type(cls, type_name):
    def apply(constructor):
      cls._provider_types[type_name] = constructor
      return constructor

    return apply


@ExternalProvider.register_provider_type('javaJar')
def java_jar(urns, provider_base_path, jar: str):

View on GitHub (pinned to 12126d8942)

Solutions

Read the chained ': {exn}' cause in the message/traceback and fix that underlying error.
Check each config key matches the provider constructor's expected parameters and types.
Verify any referenced artifacts (jars, urls) are reachable from the launching machine.
If the constructor has a bug, file/inspect in apache_beam.yaml.yaml_provider for that provider type.

Example fix

# before
- type: mavenJar
  config:
    jar: not-a-coordinate
# after
- type: mavenJar
  config:
    group_id: org.example
    artifact_id: my-lib
    version: 1.0.0

Defensive patterns

Strategy: try-catch

Validate before calling

# Pre-check constructor kwargs where possible
required = {'jar'}  # example for javaJar
if not required.issubset(spec.get('config', {})):
    raise SystemExit(f'config missing keys: {required - set(spec.get("config", {}))}')

Try / catch

try:
    provider = ExternalProvider.provider_from_spec(src, spec)
except ValueError as e:
    log.error('Provider instantiation failed: %s', e)
    log.error('Cause: %s', e.__cause__)
    raise

Prevention

Always inspect the chained cause (__cause__) for the real failure.
Validate jar paths/URLs and maven coordinates before launching.
Test provider specs with a minimal pipeline first.

When it happens

Trigger: A registered provider type whose constructor fails on the given config: bad jar path handling setup, invalid config values (wrong types, missing constructor kwargs), network/IO errors resolving the provider.

Common situations: maven/java jar provider configs with wrong coordinates; python provider config referencing modules that fail to import at construction; version strings that don't resolve.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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