Netflix/Hystrix · error · RuntimeException

You have set the bucket size to 0ms. Please set a positive

Error message

You have set the bucket size to 0ms.  Please set a positive number, so that the metric stream can be properly consumed

What it means

HealthCountsStream.getInstance(commandKey, properties) derives the health-count bucket size from metricsHealthSnapshotIntervalInMilliseconds (default 500ms); if that property was explicitly set to 0, health-count buckets cannot be created and a RuntimeException tells you to set a positive number so the metric stream (feeding the circuit breaker's snapshot) can be consumed.

Source

Thrown at hystrix-core/src/main/java/com/netflix/hystrix/metric/consumer/HealthCountsStream.java:58

 */
public class HealthCountsStream extends BucketedRollingCounterStream<HystrixCommandCompletion, long[], HystrixCommandMetrics.HealthCounts> {

    private static final ConcurrentMap<String, HealthCountsStream> streams = new ConcurrentHashMap<String, HealthCountsStream>();

    private static final int NUM_EVENT_TYPES = HystrixEventType.values().length;

    private static final Func2<HystrixCommandMetrics.HealthCounts, long[], HystrixCommandMetrics.HealthCounts> healthCheckAccumulator = new Func2<HystrixCommandMetrics.HealthCounts, long[], HystrixCommandMetrics.HealthCounts>() {
        @Override
        public HystrixCommandMetrics.HealthCounts call(HystrixCommandMetrics.HealthCounts healthCounts, long[] bucketEventCounts) {
            return healthCounts.plus(bucketEventCounts);
        }
    };


    public static HealthCountsStream getInstance(HystrixCommandKey commandKey, HystrixCommandProperties properties) {
        final int healthCountBucketSizeInMs = properties.metricsHealthSnapshotIntervalInMilliseconds().get();
        if (healthCountBucketSizeInMs == 0) {
            throw new RuntimeException("You have set the bucket size to 0ms.  Please set a positive number, so that the metric stream can be properly consumed");
        }
        final int numHealthCountBuckets = properties.metricsRollingStatisticalWindowInMilliseconds().get() / healthCountBucketSizeInMs;

        return getInstance(commandKey, numHealthCountBuckets, healthCountBucketSizeInMs);
    }

    public static HealthCountsStream getInstance(HystrixCommandKey commandKey, int numBuckets, int bucketSizeInMs) {
        HealthCountsStream initialStream = streams.get(commandKey.name());
        if (initialStream != null) {
            return initialStream;
        } else {
            final HealthCountsStream healthStream;
            synchronized (HealthCountsStream.class) {
                HealthCountsStream existingStream = streams.get(commandKey.name());
                if (existingStream == null) {
                    HealthCountsStream newStream = new HealthCountsStream(commandKey, numBuckets, bucketSizeInMs,
                            HystrixCommandMetrics.appendEventToBucket);

View on GitHub (pinned to 5ce3bc58c3)

Solutions

Set the interval to a positive value (default 500ms): hystrix.command.default.metrics.healthSnapshot.intervalInMilliseconds=500
To reduce overhead, raise the interval rather than zeroing it (e.g. 1000–5000ms)
If health metrics are truly unwanted, the interval property is not the off switch — leave it positive and ignore the stream

Example fix

# before
hystrix.command.default.metrics.healthSnapshot.intervalInMilliseconds=0
# after
hystrix.command.default.metrics.healthSnapshot.intervalInMilliseconds=500

Defensive patterns

Strategy: validation

Validate before calling

int interval = properties.metricsHealthSnapshotIntervalInMilliseconds().get();
if (interval <= 0) throw new IllegalArgumentException("healthSnapshot.intervalInMilliseconds must be > 0 (default 500)");

Type guard

null

Try / catch

Fail fast at config load — catching this at stream initialization is too late.

Prevention

Never set metrics.healthSnapshot.intervalInMilliseconds to 0
Validate Hystrix properties at application startup
Raise the interval (not zero it) to cut metrics overhead

When it happens

Trigger: Setting hystrix.command.<key>.metrics.healthSnapshot.intervalInMilliseconds=0 (or programmatically withHealthSnapshotIntervalInMilliseconds(0)) for a command whose health stream then gets initialized; often a misguided attempt to disable health metrics.

Common situations: Teams zeroing the health snapshot interval believing it disables metrics overhead; global default override via Archaius (hystrix.command.default.metrics.healthSnapshot.intervalInMilliseconds=0) breaking every command; config copy-paste from tuning guides.

Related errors

AI-assisted analysis of Netflix/Hystrix@5ce3bc58c3 (2026-08-14). Data as JSON: /api/errors/519b21b8240c2ca5. Report an issue: GitHub.