{"record":{"id":"71b300da0ca6aed3","repo":"apache/beam","slug":"starting-version-or-timestamp-must-be-specified","errorCode":null,"errorMessage":"Starting version or timestamp must be specified.","messagePattern":"Starting version or timestamp must be specified\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/delta/src/main/java/org/apache/beam/sdk/io/delta/CreateCDCReadTasksDoFn.java","lineNumber":91,"sourceCode":"    Configuration conf = new Configuration();\n    if (hadoopConfig != null) {\n      for (Map.Entry<String, String> entry : hadoopConfig.entrySet()) {\n        conf.set(entry.getKey(), entry.getValue());\n      }\n    }\n    Engine engine = DefaultEngine.create(conf);\n    Table table = Table.forPath(engine, tablePath);\n    TableImpl tableImpl = (TableImpl) table;\n\n    // 1. Resolve starting and ending versions\n    long resolvedStartVersion;\n    if (startVersion != null) {\n      resolvedStartVersion = startVersion;\n    } else if (startTimestamp != null) {\n      long startMillis = Instant.parse(startTimestamp).toEpochMilli();\n      resolvedStartVersion = tableImpl.getVersionAtOrAfterTimestamp(engine, startMillis);\n    } else {\n      throw new IllegalArgumentException(\"Starting version or timestamp must be specified.\");\n    }\n\n    long resolvedEndVersion;\n    if (endVersion != null) {\n      resolvedEndVersion = endVersion;\n    } else if (endTimestamp != null) {\n      long endMillis = Instant.parse(endTimestamp).toEpochMilli();\n      resolvedEndVersion = tableImpl.getVersionBeforeOrAtTimestamp(engine, endMillis);\n    } else {\n      resolvedEndVersion = table.getLatestSnapshot(engine).getVersion();\n    }\n\n    if (resolvedStartVersion > resolvedEndVersion) {\n      throw new IllegalArgumentException(\n          String.format(\n              \"Resolved start version %d is greater than resolved end version %d\",\n              resolvedStartVersion, resolvedEndVersion));\n    }","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/delta/src/main/java/org/apache/beam/sdk/io/delta/CreateCDCReadTasksDoFn.java#L73-L109","documentation":"CreateCDCReadTasksDoFn resolves the start of a Delta table CDC read. Exactly one of startVersion or startTimestamp must be provided to determine resolvedStartVersion; if neither is set the function cannot compute a starting point and throws. The message reflects the Delta CDC API requirement that a starting version or timestamp be specified.","triggerScenarios":"Building a Delta CDC read (tableChanges/cdc API) with both startVersion and startTimestamp null — e.g. the user set only an ending bound, or the options were misnamed so neither was populated.","commonSituations":"Option name typos (e.g. 'startingVersion' vs 'startVersion') in the CDC read builder, programmatically built options where the start bound was left unset, migration from a different Delta reader API.","solutions":["Pass startVersion (long) when you know the version: .startingVersion(5).","Otherwise pass a valid ISO-8601 startTimestamp, e.g. .startingTimestamp(\"2023-01-01T00:00:00Z\").","Fix option-name typos so the value actually reaches CreateCDCReadTasksDoFn.","Validate at pipeline construction time that at least one start bound is present."],"exampleFix":"// before\nDeltaCdc.read().tableName(\"tbl\").endingVersion(20) // no start bound\n// after\nDeltaCdc.read().tableName(\"tbl\").startingVersion(0).endingVersion(20)","handlingStrategy":"validation","validationCode":"if (startVersion == null && startTimestamp == null) {\n  throw new IllegalArgumentException(\n      \"Delta CDC read requires startingVersion or startingTimestamp\");\n}\nif (startTimestamp != null) {\n  Instant.parse(startTimestamp); // fail fast on bad format\n}","typeGuard":null,"tryCatchPattern":"try {\n  cdcPipeline.run().waitUntilFinish();\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"Starting version or timestamp must be specified\")) {\n    // fix the read builder options and relaunch\n  }\n}","preventionTips":["Always set startingVersion (often 0) or startingTimestamp in CDC reads","Centralize CDC read-option construction in one validated helper","Check option-name spelling against the API (startingVersion/startingTimestamp)"],"tags":["java","delta-lake","cdc","apache-beam","missing-argument"],"backgroundTag":"missing-required-argument","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"}