{"record":{"id":"b420fcb2ee43f59f","repo":"apache/beam","slug":"encountered-an-error-when-retrieving-a-configuration","errorCode":null,"errorMessage":"Encountered an error when retrieving a configuration","messagePattern":"Encountered an error when retrieving a configuration","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/managed/src/main/java/org/apache/beam/sdk/managed/ManagedSchemaTransformProvider.java","lineNumber":168,"sourceCode":"            managedConfig.getTransformIdentifier());\n\n    return new ManagedSchemaTransform(managedConfig, schemaTransformProvider);\n  }\n\n  static class ManagedSchemaTransform extends SchemaTransform {\n    private final ManagedConfig managedConfig;\n    private final Row underlyingRowConfig;\n    private final SchemaTransformProvider underlyingTransformProvider;\n\n    ManagedSchemaTransform(\n        ManagedConfig managedConfig, SchemaTransformProvider underlyingTransformProvider) {\n      // parse config before expansion to check if it matches underlying transform's config schema\n      Schema transformConfigSchema = underlyingTransformProvider.configurationSchema();\n      Row underlyingRowConfig;\n      try {\n        underlyingRowConfig = getRowConfig(managedConfig, transformConfigSchema);\n      } catch (Exception e) {\n        throw new IllegalArgumentException(\n            \"Encountered an error when retrieving a configuration\", e);\n      }\n\n      this.underlyingRowConfig = underlyingRowConfig;\n      this.underlyingTransformProvider = underlyingTransformProvider;\n      this.managedConfig = managedConfig;\n    }\n\n    @Override\n    public PCollectionRowTuple expand(PCollectionRowTuple input) {\n      LOG.debug(\n          \"Building transform \\\"{}\\\" with configuration: {}\",\n          underlyingTransformProvider.identifier(),\n          underlyingRowConfig);\n\n      return input.apply(underlyingTransformProvider.from(underlyingRowConfig));\n    }\n","sourceCodeStart":150,"sourceCodeEnd":186,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/managed/src/main/java/org/apache/beam/sdk/managed/ManagedSchemaTransformProvider.java#L150-L186","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before: wrong key\nMap.of(\"tablenName\", \"t\");\n// after\nMap.of(\"tableName\", \"t\");","handlingStrategy":"validation","validationCode":"Schema expected = provider.configurationSchema();\nfor (String key : configMap.keySet()) {\n  if (expected.getField(name -> name) == null) throw new IllegalArgumentException(\"Unknown config key: \" + key);\n}","typeGuard":null,"tryCatchPattern":"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; }","preventionTips":["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."],"tags":["java","apache-beam","managed-api","config"],"backgroundTag":"schema-validation-failed","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}