apache/skywalking · error · IllegalStateException

Time bucket ({timeBucket}) can't be recognized.

Error message

Time bucket ({timeBucket}) can't be recognized.

What it means

Metrics.getDurationInMinute() maps a metric's time bucket granularity to its duration in minutes: minute=1, hour=60, day=1440. Second-dimensionality buckets (and any malformed bucket value) match none of the three checks and fall through to this IllegalStateException, which names the unrecognized bucket value in the message.

Source

Thrown at oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/analysis/metrics/Metrics.java:136

        } else if (isHourBucket()) {
            return timeBucket / 100;
        } else {
            throw new IllegalStateException("Current time bucket is not in minute dimensionality");
        }
    }

    /**
     * Always get the duration for this time bucket in minute.
     */
    protected long getDurationInMinute() {
        if (isMinuteBucket()) {
            return 1;
        } else if (isHourBucket()) {
            return 60;
        } else if (isDayBucket()) {
            return 24 * 60;
        }
        throw new IllegalStateException("Time bucket (" + timeBucket + ") can't be recognized.");
    }

    private boolean isMinuteBucket() {
        return TimeBucket.isMinuteBucket(timeBucket);
    }

    private boolean isHourBucket() {
        return TimeBucket.isHourBucket(timeBucket);
    }

    private boolean isDayBucket() {
        return TimeBucket.isDayBucket(timeBucket);
    }

    private volatile StorageID id;

    @Override
    public StorageID id() {

View on GitHub (pinned to 102af09b4a)

Solutions

1. Verify the timeBucket handed to the metric matches a supported granularity (yyyyMMddHHmm, yyyyMMddHH, or yyyyMMdd) — print the offending value from the exception message
2. Fix the producer (agent or MAL/OAL rule) that generated the second-level or malformed bucket for a metrics stream
3. Override getDurationInMinute() in the custom Metrics subclass if second granularity is intentional

Example fix

// before — metrics stream fed with second buckets
long tb = TimeBucket.getTimeBucket(timestamp, DownSampling.Second);
// after — metrics streams use minute buckets
long tb = TimeBucket.getTimeBucket(timestamp, DownSampling.Minute);

boolean recognizedBucket(long tb) {
    return TimeBucket.isMinuteBucket(tb) || TimeBucket.isHourBucket(tb) || TimeBucket.isDayBucket(tb);
}

Catch IllegalStateException only at a startup validation layer and fail fast with the bucket value in the message; do not swallow it in per-record loops.

When it happens

Trigger: A Metrics instance was constructed with a second-level timeBucket (TimeBucket.getTimeBucket(ts, DownSampling.Second), format yyyyMMddHHmmss) and some code path (e.g. TTL or expiration logic) calls getDurationInMinute().

Common situations: Custom metric classes copied from Record-style (second-bucket) definitions then wired into metrics workers; a malformed timeBucket produced by custom agent code (wrong digit count); OAL/meter functions receiving an unexpected bucket format after a version upgrade.

Related errors

• Current time bucket is not in minute dimensionality
• {funcName}() requires exactly 1 argument, got {argCount}
• Cannot resolve method {simpleName}.{methodName}() in def var
• Cannot resolve field/getter {simpleName}.{fieldName} in def
• Failed to load GenAI configuration file.

AI-assisted analysis of apache/skywalking@102af09b4a (2026-08-14). Data as JSON: /api/errors/04c647ce7d0e679c. Report an issue: GitHub.