{"record":{"id":"d2001994f2f04917","repo":"apache/beam","slug":"the-following-options-are-currently-only-available-when","errorCode":null,"errorMessage":"the following options are currently only available when reading with Managed.ICEBERG_CDC: {invalidOptions}","messagePattern":"the following options are currently only available when reading with Managed\\.ICEBERG_CDC: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/iceberg/src/main/java/org/apache/beam/sdk/io/iceberg/IcebergScanConfig.java","lineNumber":434,"sourceCode":"        invalidOptions.add(\"from_timestamp\");\n      }\n      if (getToTimestamp() != null) {\n        invalidOptions.add(\"to_timestamp\");\n      }\n      if (getFromSnapshotInclusive() != null) {\n        invalidOptions.add(\"from_snapshot\");\n      }\n      if (getToSnapshot() != null) {\n        invalidOptions.add(\"to_snapshot\");\n      }\n      if (getStartingStrategy() != null) {\n        invalidOptions.add(\"starting_strategy\");\n      }\n      if (!getMetadataColumns().isEmpty()) {\n        invalidOptions.add(\"metadata_columns\");\n      }\n      if (!invalidOptions.isEmpty()) {\n        throw new IllegalArgumentException(\n            error(\n                \"the following options are currently only available when \"\n                    + \"reading with Managed.ICEBERG_CDC: \"\n                    + invalidOptions));\n      }\n    } else {\n      Set<Integer> primaryKeyIds = new HashSet<>(table.schema().identifierFieldIds());\n      checkState(\n          !primaryKeyIds.isEmpty(),\n          \"Cannot read CDC records as the table schema does not specified any primary key fields.\");\n      Set<Integer> projectedFieldIds = TypeUtil.getProjectedIds(getProjectedSchema());\n      primaryKeyIds.removeAll(projectedFieldIds);\n      checkArgument(\n          primaryKeyIds.isEmpty(),\n          \"When reading CDC records, the projected schema must not drop primary key fields. \"\n              + \"The specified configuration drops the following PK fields: %s\",\n          primaryKeyIds);\n      validateMetadataColumns(table);","sourceCodeStart":416,"sourceCodeEnd":452,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/iceberg/src/main/java/org/apache/beam/sdk/io/iceberg/IcebergScanConfig.java#L416-L452","documentation":"IcebergScanConfig.validate enforces that options exclusive to CDC streaming reads (streaming_strategy/start_strategy like starting_strategy, and metadata_columns) are only supplied when reading via Managed.ICEBERG_CDC. If any such option is set on a non-CDC scan configuration, IllegalArgumentException is thrown listing the invalid options.","triggerScenarios":"Calling validate() (from expand or the thrown/keepException/dropException/... option paths) with starting_strategy or metadata_columns set while the scan is not a Managed.ICEBERG_CDC read, at IcebergScanConfig.java:434.","commonSituations":"Reusing one options object for both batch and CDC reads; leftover CDC options in a batch pipeline template; switching a pipeline from CDC to batch without clearing options.","solutions":["Remove starting_strategy and metadata_columns from the configuration when not using Managed.ICEBERG_CDC.","Switch the read to Managed.ICEBERG_CDC if you actually need these options.","Build separate configuration objects for CDC and non-CDC reads instead of sharing one.","Conditionally set CDC-only options in pipeline construction code."],"exampleFix":"// before\nIcebergScanConfig config = IcebergScanConfig.builder()\n    .setStartingStrategy(\"INCLUSIVE\") // CDC-only\n    .build();\n\n// after\nIcebergScanConfig config = IcebergScanConfig.builder().build(); // or use Managed.ICEBERG_CDC","handlingStrategy":"validation","validationCode":"if (!isCdcRead && (config.getStartingStrategy() != null || !config.getMetadataColumns().isEmpty())) {\n  throw new IllegalArgumentException(\"starting_strategy/metadata_columns require Managed.ICEBERG_CDC\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  scanConfig.validate();\n} catch (IllegalArgumentException e) {\n  LOG.error(\"CDC-only options in non-CDC scan: {}\", e.getMessage());\n}","preventionTips":["Keep separate config objects for CDC and batch scans.","Strip CDC-only options when switching a pipeline to batch.","Read the Managed.ICEBERG_CDC option docs before reuse.","Centralize scan config construction with mode-aware guards."],"tags":["java","iceberg","config-validation","cdc"],"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-14T16:17:12.679Z"}