locustio/locust · error · ValueError

StatsEntry.use_response_times_cache must be set to True to c

Error message

StatsEntry.use_response_times_cache must be set to True to calculate the _current_ response time percentile

What it means

get_current_response_time_percentile() needs the sliding response-times cache to answer 'what was the p95 over the last ~10 seconds'. If StatsEntry.use_response_times_cache is False (the default for entries that only track aggregate history), the current percentile cannot be computed, so the method raises ValueError.

Source

Thrown at locust/stats.py:620

        Get the response time that a certain number of percent of the requests
        finished within.

        Percent specified in range: 0.0 - 1.0
        """
        # response_times only holds non-None samples, so None (async) requests
        # must be excluded from the denominator, just like in avg/median
        return calculate_response_time_percentile(
            self.response_times, self.num_requests - self.num_none_requests, percent
        )

    def get_current_response_time_percentile(self, percent: float) -> int | None:
        """
        Calculate the *current* response time for a certain percentile. We use a sliding
        window of (approximately) the last 10 seconds (specified by CURRENT_RESPONSE_TIME_PERCENTILE_WINDOW)
        when calculating this.
        """
        if not self.use_response_times_cache:
            raise ValueError(
                "StatsEntry.use_response_times_cache must be set to True to calculate the _current_ response time percentile"
            )
        # First, we want to determine which of the cached response_times dicts we should
        # use to get response_times for approximately 10 seconds ago.
        t = int(time.time())
        # Since we can't be sure that the cache contains an entry for every second.
        # We'll construct a list of timestamps which we consider acceptable keys to be used
        # when trying to fetch the cached response_times. We construct this list in such a way
        # that it's ordered by preference by starting to add t-10, then t-11, t-9, t-12, t-8,
        # and so on
        acceptable_timestamps: list[int] = []
        acceptable_timestamps.append(t - CURRENT_RESPONSE_TIME_PERCENTILE_WINDOW)
        for i in range(1, 9):
            acceptable_timestamps.append(t - CURRENT_RESPONSE_TIME_PERCENTILE_WINDOW - i)
            acceptable_timestamps.append(t - CURRENT_RESPONSE_TIME_PERCENTILE_WINDOW + i)

        cached: CachedResponseTimes | None = None
        if self.response_times_cache is not None:

View on GitHub (pinned to f391a716e1)

Solutions

Create the StatsEntry with use_response_times_cache=True before calling get_current_response_time_percentile()
Use get_response_time_percentile() (aggregate, whole-run) instead if you don't need the sliding window
Enable the cache globally by configuring stats.CURRENT_RESPONSE_TIME_PERCENTILE settings in your custom entry setup

Example fix

// before
entry = env.stats.get(name, method)
entry.get_current_response_time_percentile(0.95)
// after
entry = env.stats.get(name, method, use_response_times_cache=True)
entry.get_current_response_time_percentile(0.95)

Defensive patterns

Strategy: validation

Validate before calling

if not entry.use_response_times_cache:
    raise ValueError("enable use_response_times_cache before reading current percentiles")

Try / catch

try:
    p = entry.get_current_response_time_percentile(0.95)
except ValueError:
    p = entry.get_response_time_percentile(0.95)  # aggregate fallback

Prevention

Always construct StatsEntry with use_response_times_cache=True when you need sliding-window percentiles
Document which stats entries support current percentiles
Prefer aggregate percentiles unless the 10s window is required

When it happens

Trigger: Calling entry.get_current_response_time_percentile(p) on a StatsEntry whose use_response_times_cache was not set to True at creation; this happens in update_stats_history/_percentile_fields if entries are configured without the cache.

Common situations: Custom stats reporters or plugins reading current percentiles on entries they created manually; code building StatsEntry without passing use_response_times_cache=True; versions where custom entries previously worked with aggregate-only data.

Related errors

AI-assisted analysis of locustio/locust@f391a716e1 (2026-08-29). Data as JSON: /api/errors/84841be66dd852fe. Report an issue: GitHub.