{"record":{"id":"35c842bb38de9ccd","repo":"apache/beam","slug":"unrecognized-s-position-to-create-shard-filter-with","errorCode":null,"errorMessage":"Unrecognized '%s' position to create shard filter with","messagePattern":"Unrecognized '(.+?)' position to create shard filter with","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/amazon-web-services2/src/main/java/org/apache/beam/sdk/io/aws2/kinesis/ShardListingUtils.java","lineNumber":74,"sourceCode":"    ShardFilter shardFilter =\n        buildShardFilterForStartingPoint(kinesisClient, streamName, startingPoint);\n    return listShards(kinesisClient, streamName, shardFilter);\n  }\n\n  static ShardFilter buildShardFilterForStartingPoint(\n      KinesisClient kinesisClient, String streamName, StartingPoint startingPoint)\n      throws InterruptedException {\n    InitialPositionInStream position = startingPoint.getPosition();\n    switch (position) {\n      case LATEST:\n        return ShardFilter.builder().type(ShardFilterType.AT_LATEST).build();\n      case TRIM_HORIZON:\n        return ShardFilter.builder().type(ShardFilterType.AT_TRIM_HORIZON).build();\n      case AT_TIMESTAMP:\n        return buildShardFilterForTimestamp(\n            kinesisClient, streamName, startingPoint.getTimestamp());\n      default:\n        throw new IllegalArgumentException(\n            String.format(\"Unrecognized '%s' position to create shard filter with\", position));\n    }\n  }\n\n  private static ShardFilter buildShardFilterForTimestamp(\n      KinesisClient kinesisClient, String streamName, Instant startingPointTimestamp)\n      throws InterruptedException {\n    StreamDescriptionSummary streamDescription = describeStreamSummary(kinesisClient, streamName);\n\n    Instant streamCreationTimestamp = TimeUtil.toJoda(streamDescription.streamCreationTimestamp());\n    if (streamCreationTimestamp.isAfter(startingPointTimestamp)) {\n      return ShardFilter.builder().type(ShardFilterType.AT_TRIM_HORIZON).build();\n    }\n\n    Duration retentionPeriod = Duration.standardHours(streamDescription.retentionPeriodHours());\n\n    Instant streamTrimHorizonTimestamp =\n        Instant.now()","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/amazon-web-services2/src/main/java/org/apache/beam/sdk/io/aws2/kinesis/ShardListingUtils.java#L56-L92","documentation":"buildShardFilterForStartingPoint in ShardListingUtils maps an InitialPositionInStream (LATEST, TRIM_HORIZON, AT_TIMESTAMP) to an AWS SDK v2 ShardFilter used by listShards. Any position value outside that switch's known cases falls into the default branch and throws this IllegalArgumentException. It effectively means the StartingPoint supplied to the Kinesis IO contains a position the shard-filter mapping does not handle.","triggerScenarios":"Calling ShardListingUtils.buildShardFilterForStartingPoint (indirectly via shardFilter/listShardsAtPoint) with a StartingPoint whose InitialPositionInStream is neither LATEST, TRIM_HORIZON nor AT_TIMESTAMP — typically a newly added enum constant or a custom/deserialized position value.","commonSituations":"Beam pipeline configured with a custom InitialPositionInStream extension; a Beam version upgrade introduced a new position constant while code (or a copied fork) still uses the old switch; deserialization of a serialized StartingPoint from an older pipeline representation yielding an unexpected enum value.","solutions":["Use only InitialPositionInStream.LATEST, TRIM_HORIZON or AT_TIMESTAMP when building the StartingPoint for Kinesis IO.","If a new position constant was added upstream, upgrade the Beam AWS2 SDK module (or your fork) so the switch maps it to a ShardFilter type.","Check the serialized pipeline/options for a corrupted or foreign InitialPositionInStream value and reconfigure the consumer with a valid position."],"exampleFix":"// before\nStartingPoint sp = new StartingPoint(myCustomPosition);\n// after\nStartingPoint sp = new StartingPoint(InitialPositionInStream.AT_TIMESTAMP, ReadableInstant timestamp);","handlingStrategy":"validation","validationCode":"if (position != InitialPositionInStream.LATEST\n    && position != InitialPositionInStream.TRIM_HORIZON\n    && position != InitialPositionInStream.AT_TIMESTAMP) {\n  throw new IllegalArgumentException(\"Unsupported position: \" + position);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only construct StartingPoint from the documented InitialPositionInStream constants","Re-check enum constants after Beam upgrades"],"tags":["kinesis","invalid-enum-value","configuration"],"backgroundTag":"invalid-enum-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}