apache/beam · error · IllegalArgumentException

Only FeedRangeEpkImpl are supported. got: feedRange

Error message

Only FeedRangeEpkImpl are supported. got: feedRange

What it means

NormalizedRange.fromFeedRange only understands Azure Cosmos DB FeedRangeEpkImpl instances; any other FeedRange implementation is rejected with IllegalArgumentException('Only FeedRangeEpkImpl are supported. got: <feedRange>'). The connector can only partition by explicit EPK ranges.

Solutions

Use FeedRangeEpkImpl (explicit PK range strings) when configuring the Cosmos read.
Convert a FeedRangePartitionKey to its equivalent EPK range before passing it.
Check the Cosmos SDK version — ensure feed range construction matches what the connector supports.
Log/inspect the feedRange's class to confirm what implementation was supplied.

Example fix

// before
FeedRange range = FeedRange.forPartitionKey(new PartitionKey("pk"));
NormalizedRange.fromFeedRange(range);
// after
FeedRange range = new FeedRangeEpkImpl(new Range<String>(minHex, maxHex, true));
NormalizedRange.fromFeedRange(range);

Defensive patterns

Strategy: type-guard

Validate before calling

// verify the feed range implementation before passing it in
if (!(feedRange instanceof FeedRangeEpkImpl)) {
  throw new IllegalArgumentException("convert to FeedRangeEpkImpl first");
}

Type guard

boolean isEpkRange(FeedRange r) { return r instanceof FeedRangeEpkImpl; }

Try / catch

try {
  NormalizedRange nr = NormalizedRange.fromFeedRange(feedRange);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("Only FeedRangeEpkImpl")) {
    feedRange = toEpkRange(feedRange); // convert PartitionKey range to EPK range
  }
}

Prevention

Always construct FeedRangeEpkImpl for Cosmos connector reads
Convert partition-key feed ranges to EPK ranges explicitly
Pin a Cosmos SDK version compatible with the connector
Unit-test feed range construction for your query paths

When it happens

Trigger: Passing a FeedRange that is not a FeedRangeEpkImpl (e.g., FeedRangePartitionKey or FeedRangePredicate) into NormalizedRange.fromFeedRange.

Common situations: Using partition-key-based feed ranges from the Cosmos SDK where the connector expects EPK string ranges, constructing feed ranges via SDK helpers that return other implementations, Cosmos SDK version changes.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at sdks/java/io/azure-cosmos/src/main/java/org/apache/beam/sdk/io/azure/cosmos/NormalizedRange.java:54

  public static NormalizedRange fromFeedRange(FeedRange feedRange) {
    if (feedRange instanceof FeedRangeEpkImpl) {
      FeedRangeEpkImpl ekp = (FeedRangeEpkImpl) feedRange;
      Range<String> range = ekp.getRange();
      String min = range.getMin();
      String max = range.getMax();

      if (!range.isMinInclusive()) {
        min = new BigInteger(min, 16).add(BigInteger.ONE).toString(16);
      }

      if (range.isMaxInclusive()) {
        max = new BigInteger(max, 16).subtract(BigInteger.ONE).toString(16);
      }

      return new NormalizedRange(min, max);
    } else {
      throw new IllegalArgumentException("Only FeedRangeEpkImpl are supported. got: " + feedRange);
    }
  }

  public NormalizedRange(String minInclusive, String maxExclusive) {
    this.minInclusive = minInclusive;
    this.maxExclusive = maxExclusive;
  }

  public FeedRange toFeedRange() {
    return new FeedRangeEpkImpl(new Range<>(minInclusive, maxExclusive, true, false));
  }
}

View on GitHub (pinned to 12126d8942)