{"record":{"id":"ba3178685d428e62","repo":"apache/beam","slug":"unable-to-encode-int64-histogram-bucket-is-not-recognized","errorCode":null,"errorMessage":"Unable to encode Int64 Histogram, bucket is not recognized","messagePattern":"Unable to encode Int64 Histogram, bucket is not recognized","errorType":"exception","errorClass":"HistogramParsingException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/util/HistogramData.java","lineNumber":325,"sourceCode":"\n      BucketOptions.Builder bucketBuilder = BucketOptions.newBuilder();\n      bucketBuilder.setLinear(linearOptions);\n      builder.setBucketOptions(bucketBuilder.build());\n\n    } else if (this.getBucketType() instanceof HistogramData.ExponentialBuckets) {\n      HistogramData.ExponentialBuckets buckets =\n          (HistogramData.ExponentialBuckets) this.getBucketType();\n\n      Base2Exponent.Builder base2ExpBuilder = Base2Exponent.newBuilder();\n      base2ExpBuilder.setNumberOfBuckets(numberOfBuckets);\n      base2ExpBuilder.setScale(buckets.getScale());\n      Base2Exponent exponentialOptions = base2ExpBuilder.build();\n\n      BucketOptions.Builder bucketBuilder = BucketOptions.newBuilder();\n      bucketBuilder.setExponential(exponentialOptions);\n      builder.setBucketOptions(bucketBuilder.build());\n    } else {\n      throw new HistogramParsingException(\n          \"Unable to encode Int64 Histogram, bucket is not recognized\");\n    }\n\n    builder.setCount(this.getTotalCount());\n\n    for (long val : this.getBucketCount()) {\n      builder.addBucketCounts(val);\n    }\n    return builder.build();\n  }\n\n  // /** Creates a {@link HistogramData} instance from its proto {@link HistogramValue}. */\n  // public static HistogramData fromProto(HistogramValue proto) {\n  //   HistgramValue value = new HistgramValue();\n  //   return new HistogramValue(proto);\n  // }\n\n  /**","sourceCodeStart":307,"sourceCodeEnd":343,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/util/HistogramData.java#L307-L343","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nHistogramData h = HistogramData.customBucketHistogram(...); // non-standard buckets\nencodeInt64Histogram(h);\n// after\nHistogramData h = HistogramData.exponential(BucketsType.EXPONENTIAL, HistogramData.LinearBuckets.of(0, 10, 20));\nencodeInt64Histogram(h); // standard bucket options encode cleanly","handlingStrategy":"validation","validationCode":"if (!(h.getBuckets() instanceof HistogramData.LinearBuckets)\n    && !(h.getBuckets() instanceof HistogramData.ExponentialBuckets)) {\n  throw new IllegalArgumentException(\"Histogram must use Linear or Exponential buckets before encoding\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  encodeInt64Histogram(h);\n} catch (HistogramParsingException e) {\n  LOG.error(\"Histogram bucket options not encodable: {}\", e.getMessage(), e);\n  throw e;\n}","preventionTips":["Only construct histograms with LinearBuckets.of or ExponentialBuckets.of","Keep Beam SDK versions aligned across producers and consumers of histogram protos"],"tags":["java","histogram","metrics","encoding"],"backgroundTag":"unsupported-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"}