What causes "Percentile ({percentile}) is not currently cached" in Netflix/Hystrix?

Pass basis points: 9900 for p99, 9990 for p99.9 — check against the switch's cached set

Netflix/Hystrix · error · IllegalArgumentException

Percentile ( ) is not currently cached

Error message

Percentile ({percentile}) is not currently cached

What it means

CachedValuesHistogram.getCachedPercentile(percentile) only serves percentiles it precomputed in basis points: 0, 2500, 5000, 7000, 7500, 8000, 8500, 9000, 9500, 9900, 9950, 9990, 9995, 9999, 10000 (i.e. mean, p25–p100 in the fixed step set). Any other integer throws IllegalArgumentException('Percentile (x) is not currently cached'). Arbitrary percentiles require the underlying HdrHistogram, not the cached accessor.

Solutions

Pass basis points: 9900 for p99, 9990 for p99.9 — check against the switch's cached set
Use the full HdrHistogram API (histogram.getValueAtPercentile(x)) for arbitrary percentiles instead of the cached accessor
Use the public HystrixCommandMetrics APIs (getExecutionTimePercentile) which translate correctly

Example fix

// before
long p99 = stream.getLatest().getCachedPercentile(99); // percent, throws
// after
long p99 = stream.getLatest().getCachedPercentile(9900); // basis points (99.00%)

Defensive patterns

Strategy: validation

Validate before calling

static boolean isCachedPercentile(int bps) {
  return bps==0||bps==2500||bps==5000||bps==7000||bps==7500||bps==8000||bps==8500
      ||bps==9000||bps==9500||bps==9900||bps==9950||bps==9990||bps==9995||bps==9999||bps==10000; }
if (!isCachedPercentile(p)) p = 9900; // or use full histogram

Type guard

null

Try / catch

Not worth catching — validate the basis-point value or use histogram.getValueAtPercentile() for arbitrary percentiles.

Prevention

Remember the API takes basis points (9900 = 99%), not percent
Use getValueAtPercentile on the underlying HdrHistogram for non-cached percentiles

When it happens

Trigger: Calling getCachedPercentile() with values like 1, 990, 9905, 1234, or 9990 vs 99900 — anything not in the switch; common when passing a percentile as percent (99) instead of basis points (9900), or requesting p98/p99.9 variants that were never cached.

Common situations: Custom dashboards/metrics publishers asking for percent values instead of basis points (99 instead of 9900); requesting uncached percentiles like p98; code ported from getValueAtPercentile (HdrHistogram, arbitrary values) to the cached fast path.

Related errors

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

Appendix: source

Thrown at hystrix-core/src/main/java/com/netflix/hystrix/metric/CachedValuesHistogram.java:139

            case 4000: return p40;
            case 4500: return p45;
            case 5000: return p50;
            case 5500: return p55;
            case 6000: return p60;
            case 6500: return p65;
            case 7000: return p70;
            case 7500: return p75;
            case 8000: return p80;
            case 8500: return p85;
            case 9000: return p90;
            case 9500: return p95;
            case 9900: return p99;
            case 9950: return p99_5;
            case 9990: return p99_9;
            case 9995: return p99_95;
            case 9999: return p99_99;
            case 10000: return p100;
            default: throw new IllegalArgumentException("Percentile (" + percentile + ") is not currently cached");
        }
    }

    public long getTotalCount() {
        return totalCount;
    }

    public static Histogram getNewHistogram() {
        return new Histogram(NUMBER_SIGNIFICANT_DIGITS);
    }
}

View on GitHub (pinned to 5ce3bc58c3)