apache/beam · error · HistogramParsingException

Unable to encode Int64 Histogram, bucket is not recognized

Error message

Unable to encode Int64 Histogram, bucket is not recognized

What it means

HistogramData.toProto() converts an Int64 Histogram into its protobuf representation. The histogram's bucket options must be LinearBuckets or ExponentialBuckets; any other BucketOptions subtype cannot be encoded, so this custom HistogramParsingException is thrown.

Solutions

Ensure the histogram was constructed with HistogramData.LinearBuckets.of(...) or ExponentialBuckets.of(...)
Check whether the data came from a proto produced by a different Beam/language SDK version and upgrade to a compatible version
Convert custom bucket schemes to linear/exponential buckets before encoding

Example fix

// before
HistogramData h = HistogramData.customBucketHistogram(...); // non-standard buckets
encodeInt64Histogram(h);
// after
HistogramData h = HistogramData.exponential(BucketsType.EXPONENTIAL, HistogramData.LinearBuckets.of(0, 10, 20));
encodeInt64Histogram(h); // standard bucket options encode cleanly

Defensive patterns

Strategy: validation

Validate before calling

if (!(h.getBuckets() instanceof HistogramData.LinearBuckets)
    && !(h.getBuckets() instanceof HistogramData.ExponentialBuckets)) {
  throw new IllegalArgumentException("Histogram must use Linear or Exponential buckets before encoding");
}

Try / catch

try {
  encodeInt64Histogram(h);
} catch (HistogramParsingException e) {
  LOG.error("Histogram bucket options not encodable: {}", e.getMessage(), e);
  throw e;
}

Prevention

Only construct histograms with LinearBuckets.of or ExponentialBuckets.of
Keep Beam SDK versions aligned across producers and consumers of histogram protos

When it happens

Trigger: Encoding a HistogramData whose bucket options are neither Linear nor Exponential — typically a custom BucketOptions implementation or a histogram deserialized from a proto with an unrecognized bucket-options oneof case.

Common situations: Cross-version or cross-language data exchange where a newer/other SDK produced bucket options this Beam version can't encode; custom histogram types passed into metrics/export paths expecting standard buckets.

Related errors

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/HistogramData.java:325

      BucketOptions.Builder bucketBuilder = BucketOptions.newBuilder();
      bucketBuilder.setLinear(linearOptions);
      builder.setBucketOptions(bucketBuilder.build());

    } else if (this.getBucketType() instanceof HistogramData.ExponentialBuckets) {
      HistogramData.ExponentialBuckets buckets =
          (HistogramData.ExponentialBuckets) this.getBucketType();

      Base2Exponent.Builder base2ExpBuilder = Base2Exponent.newBuilder();
      base2ExpBuilder.setNumberOfBuckets(numberOfBuckets);
      base2ExpBuilder.setScale(buckets.getScale());
      Base2Exponent exponentialOptions = base2ExpBuilder.build();

      BucketOptions.Builder bucketBuilder = BucketOptions.newBuilder();
      bucketBuilder.setExponential(exponentialOptions);
      builder.setBucketOptions(bucketBuilder.build());
    } else {
      throw new HistogramParsingException(
          "Unable to encode Int64 Histogram, bucket is not recognized");
    }

    builder.setCount(this.getTotalCount());

    for (long val : this.getBucketCount()) {
      builder.addBucketCounts(val);
    }
    return builder.build();
  }

  // /** Creates a {@link HistogramData} instance from its proto {@link HistogramValue}. */
  // public static HistogramData fromProto(HistogramValue proto) {
  //   HistgramValue value = new HistgramValue();
  //   return new HistogramValue(proto);
  // }

  /**

View on GitHub (pinned to 12126d8942)