{"record":{"id":"aab0fcb3711f805a","repo":"aeron-io/aeron","slug":"unsupported-time-unit-clustertimeunit","errorCode":null,"errorMessage":"unsupported time unit: <clusterTimeUnit>","messagePattern":"unsupported time unit: <clusterTimeUnit>","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/service/ClusterClock.java","lineNumber":135,"sourceCode":"     * @return a corresponding {@link TimeUnit}, if {@link ClusterTimeUnit#NULL_VAL} is passed then defaults\n     * to {@link TimeUnit#MILLISECONDS}.\n     */\n    static TimeUnit map(final ClusterTimeUnit clusterTimeUnit)\n    {\n        switch (clusterTimeUnit)\n        {\n            case NULL_VAL:\n            case MILLIS:\n                return TimeUnit.MILLISECONDS;\n\n            case MICROS:\n                return TimeUnit.MICROSECONDS;\n\n            case NANOS:\n                return TimeUnit.NANOSECONDS;\n        }\n\n        throw new IllegalArgumentException(\"unsupported time unit: \" + clusterTimeUnit);\n    }\n}\n","sourceCodeStart":117,"sourceCodeEnd":138,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/service/ClusterClock.java#L117-L138","documentation":"ClusterClock.map() converts a ClusterTimeUnit enum value into a java.util.concurrent.TimeUnit. The enum switch only covers SECONDS, MILLIS, MICROS and NANOS; if a ClusterTimeUnit value outside those is passed (e.g. a future/unknown ordinal decoded from a mark file or log header), IllegalArgumentException is thrown. It signals an unrecognized time unit value reaching the mapping function.","triggerScenarios":"Calling ClusterClock.map(clusterTimeUnit) with a ClusterTimeUnit value not handled by the switch — typically a null reference unwrapped oddly, or an UNKNOWN/invalid enum value decoded from persisted cluster data whose schema is newer or corrupt.","commonSituations":"Restoring a cluster mark file or snapshot written by a different Aeron version that introduced a new ClusterTimeUnit; hand-crafted tests passing null or UNKNOWN; corrupt stored clusterTimeUnit field.","solutions":["Check the ClusterTimeUnit value being passed; ensure it is one of SECONDS, MILLIS, MICROS, NANOS.","Verify the mark file / persisted cluster data was produced by the same Aeron version as the running software.","If you control the code, validate the unit before calling ClusterClock.map and default to a supported unit."],"exampleFix":"// before\nTimeUnit unit = ClusterClock.map(clusterTimeUnit);\n// after\nif (clusterTimeUnit == null || clusterTimeUnit == ClusterTimeUnit.UNKNOWN) {\n    clusterTimeUnit = ClusterTimeUnit.MILLIS; // or fail fast with a clear message\n}\nTimeUnit unit = ClusterClock.map(clusterTimeUnit);","handlingStrategy":"validation","validationCode":"// java\nif (clusterTimeUnit == null) throw new IllegalArgumentException(\"clusterTimeUnit required\");\nswitch (clusterTimeUnit) {\n    case SECONDS: case MILLIS: case MICROS: case NANOS: break;\n    default: throw new IllegalArgumentException(\"unsupported ClusterTimeUnit: \" + clusterTimeUnit);\n}\nTimeUnit unit = ClusterClock.map(clusterTimeUnit);","typeGuard":"static boolean isSupported(ClusterTimeUnit u) {\n    return u == ClusterTimeUnit.SECONDS || u == ClusterTimeUnit.MILLIS ||\n           u == ClusterTimeUnit.MICROS || u == ClusterTimeUnit.NANOS;\n}","tryCatchPattern":"try {\n    TimeUnit unit = ClusterClock.map(clusterTimeUnit);\n} catch (IllegalArgumentException e) {\n    // fall back to a default unit or surface a config error\n    TimeUnit unit = TimeUnit.MILLISECONDS;\n}","preventionTips":["Never pass enum values decoded from persisted files without validating against the current schema.","Reject UNKNOWN/missing time units at configuration load time.","Keep the Aeron version identical across cluster nodes to avoid new enum values."],"tags":["java","time-unit","enum","illegal-argument"],"backgroundTag":"invalid-enum-value","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}