{"record":{"id":"04c647ce7d0e679c","repo":"apache/skywalking","slug":"time-bucket-timebucket-can-t-be-recognized","errorCode":null,"errorMessage":"Time bucket ({timeBucket}) can't be recognized.","messagePattern":"Time bucket \\((.+?)\\) can't be recognized\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/analysis/metrics/Metrics.java","lineNumber":136,"sourceCode":"        } else if (isHourBucket()) {\n            return timeBucket / 100;\n        } else {\n            throw new IllegalStateException(\"Current time bucket is not in minute dimensionality\");\n        }\n    }\n\n    /**\n     * Always get the duration for this time bucket in minute.\n     */\n    protected long getDurationInMinute() {\n        if (isMinuteBucket()) {\n            return 1;\n        } else if (isHourBucket()) {\n            return 60;\n        } else if (isDayBucket()) {\n            return 24 * 60;\n        }\n        throw new IllegalStateException(\"Time bucket (\" + timeBucket + \") can't be recognized.\");\n    }\n\n    private boolean isMinuteBucket() {\n        return TimeBucket.isMinuteBucket(timeBucket);\n    }\n\n    private boolean isHourBucket() {\n        return TimeBucket.isHourBucket(timeBucket);\n    }\n\n    private boolean isDayBucket() {\n        return TimeBucket.isDayBucket(timeBucket);\n    }\n\n    private volatile StorageID id;\n\n    @Override\n    public StorageID id() {","sourceCodeStart":118,"sourceCodeEnd":154,"githubUrl":"https://github.com/apache/skywalking/blob/102af09b4a56064e22050dded10e2c52e490d040/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/analysis/metrics/Metrics.java#L118-L154","documentation":"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.","triggerScenarios":"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().","commonSituations":"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.","solutions":["Verify the timeBucket handed to the metric matches a supported granularity (yyyyMMddHHmm, yyyyMMddHH, or yyyyMMdd) — print the offending value from the exception message","Fix the producer (agent or MAL/OAL rule) that generated the second-level or malformed bucket for a metrics stream","Override getDurationInMinute() in the custom Metrics subclass if second granularity is intentional"],"exampleFix":"// before — metrics stream fed with second buckets\nlong tb = TimeBucket.getTimeBucket(timestamp, DownSampling.Second);\n// after — metrics streams use minute buckets\nlong tb = TimeBucket.getTimeBucket(timestamp, DownSampling.Minute);","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"boolean recognizedBucket(long tb) {\n    return TimeBucket.isMinuteBucket(tb) || TimeBucket.isHourBucket(tb) || TimeBucket.isDayBucket(tb);\n}","tryCatchPattern":"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.","preventionTips":["Generate metrics timeBuckets only via TimeBucket.getTimeBucket with an explicit DownSampling","Validate incoming bucket formats at the receiver boundary in custom receivers","The exception message prints the offending value — use it to trace which producer emitted the bad bucket"],"tags":["metrics","time-bucket","validation","core","custom-function"],"backgroundTag":null,"analyzedSha":"102af09b4a56064e22050dded10e2c52e490d040","analyzedAt":"2026-08-14T10:47:52.647Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}