apache/beam · error · IllegalArgumentException

Encountered an error when retrieving a configuration

Error message

Encountered an error when retrieving a configuration

What it means

When building the ManagedSchemaTransform, the managed configuration is parsed against the underlying SchemaTransformProvider's configuration schema (getRowConfig). If any exception occurs validating/converting the managed config Row into the underlying provider's expected Row config, it is rethrown as this IllegalArgumentException. The supplied managed config does not match the underlying transform's config schema.

Source

Thrown at sdks/java/managed/src/main/java/org/apache/beam/sdk/managed/ManagedSchemaTransformProvider.java:168

            managedConfig.getTransformIdentifier());

    return new ManagedSchemaTransform(managedConfig, schemaTransformProvider);
  }

  static class ManagedSchemaTransform extends SchemaTransform {
    private final ManagedConfig managedConfig;
    private final Row underlyingRowConfig;
    private final SchemaTransformProvider underlyingTransformProvider;

    ManagedSchemaTransform(
        ManagedConfig managedConfig, SchemaTransformProvider underlyingTransformProvider) {
      // parse config before expansion to check if it matches underlying transform's config schema
      Schema transformConfigSchema = underlyingTransformProvider.configurationSchema();
      Row underlyingRowConfig;
      try {
        underlyingRowConfig = getRowConfig(managedConfig, transformConfigSchema);
      } catch (Exception e) {
        throw new IllegalArgumentException(
            "Encountered an error when retrieving a configuration", e);
      }

      this.underlyingRowConfig = underlyingRowConfig;
      this.underlyingTransformProvider = underlyingTransformProvider;
      this.managedConfig = managedConfig;
    }

    @Override
    public PCollectionRowTuple expand(PCollectionRowTuple input) {
      LOG.debug(
          "Building transform \"{}\" with configuration: {}",
          underlyingTransformProvider.identifier(),
          underlyingRowConfig);

      return input.apply(underlyingTransformProvider.from(underlyingRowConfig));
    }

View on GitHub (pinned to 12126d8942)

Solutions

Inspect the chained cause to see which field failed validation and correct the config key/type.
Query the underlying provider's configurationSchema() (or docs) and align the config exactly.
Use ManagedCatalog (or identifier-specific schema printing) to obtain a valid config template.
Verify Beam version compatibility: config schemas may differ between releases.

Example fix

// before: wrong key
Map.of("tablenName", "t");
// after
Map.of("tableName", "t");

Defensive patterns

Strategy: validation

Validate before calling

Schema expected = provider.configurationSchema();
for (String key : configMap.keySet()) {
  if (expected.getField(name -> name) == null) throw new IllegalArgumentException("Unknown config key: " + key);
}

Try / catch

try { return Managed.write(Managed.SQLSERVER, config); } catch (IllegalArgumentException e) { LOG.error("Managed config rejected: {}", e.getCause() != null ? e.getCause().getMessage() : e.getMessage()); throw e; }

Prevention

Generate configs from the provider's configurationSchema(), not by hand.
Keep config YAML in version control and review against the Beam release notes.
Add a pipeline-construction-time dry run in CI that expands the managed transform.

When it happens

Trigger: Passing a config map/Row to Managed.read/write whose keys or types do not match the underlying provider's configurationSchema (e.g. wrong field name, wrong type, missing required field).

Common situations: Hand-written YAML/JSON config with typos in parameter names, passing parameters belonging to a different connector version, or using a config schema from an older Beam release after an upgrade.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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