{"record":{"id":"c3e03130e2db6020","repo":"netty/netty","slug":"fatal-could-not-find-a-clock-for-clock-gettime","errorCode":null,"errorMessage":"FATAL: could not find a clock for clock_gettime!\n","messagePattern":"FATAL: could not find a clock for clock_gettime!\n","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"transport-native-kqueue/src/main/c/netty_kqueue_native.c","lineNumber":407,"sourceCode":"    if (netty_jni_util_register_natives(env, packagePrefix, NATIVE_CLASSNAME, fixed_method_table, fixed_method_table_size) != 0) {\n        goto error;\n    }\n    nativeRegistered = 1;\n\n    if (netty_kqueue_bsdsocket_JNI_OnLoad(env, packagePrefix) == JNI_ERR) {\n        goto error;\n    }\n    bsdsocketOnLoadCalled = 1;\n\n    if (netty_kqueue_eventarray_JNI_OnLoad(env, packagePrefix) == JNI_ERR) {\n        goto error;\n    }\n    eventarrayOnLoadCalled = 1;\n\n    // Initialize this module\n\n    if (!netty_unix_util_initialize_wait_clock(&waitClockId)) {\n        fprintf(stderr, \"FATAL: could not find a clock for clock_gettime!\\n\");\n        fflush(stderr);\n        goto error;\n    }\n\n    staticPackagePrefix = packagePrefix;\n    return NETTY_JNI_UTIL_JNI_VERSION;\nerror:\n   if (staticallyRegistered == 1) {\n        netty_jni_util_unregister_natives(env, packagePrefix, STATICALLY_CLASSNAME);\n   }\n   if (nativeRegistered == 1) {\n        netty_jni_util_unregister_natives(env, packagePrefix, NATIVE_CLASSNAME);\n   }\n   if (bsdsocketOnLoadCalled == 1) {\n       netty_kqueue_bsdsocket_JNI_OnUnLoad(env, packagePrefix);\n   }\n   if (eventarrayOnLoadCalled == 1) {\n       netty_kqueue_eventarray_JNI_OnUnLoad(env, packagePrefix);","sourceCodeStart":389,"sourceCodeEnd":425,"githubUrl":"https://github.com/netty/netty/blob/70040aacae241e9ba371e758f5b86e470bd77ad1/transport-native-kqueue/src/main/c/netty_kqueue_native.c#L389-L425","documentation":"Printed to stderr (not a thrown exception) during the kqueue native library's JNI_OnLoad, when netty_unix_util_initialize_wait_clock cannot obtain any usable clock via clock_gettime. That function tries CLOCK_MONOTONIC_COARSE, CLOCK_MONOTONIC_RAW, CLOCK_MONOTONIC, CLOCK_REALTIME_COARSE, and CLOCK_REALTIME in order; if all return non-zero it gives up, prints this FATAL message, and JNI_OnLoad returns JNI_ERR — so the kqueue native transport fails to load and KQueueEventLoopGroup cannot be created.","triggerScenarios":"Loading the netty kqueue native transport on a BSD/macOS system where clock_gettime fails for every clock ID — e.g. a seccomp/container/AppArmor policy blocking clock_gettime/clock_gettime64, a stripped or broken libc, an unsupported/old kernel, or running under a sandbox that denies the time syscalls.","commonSituations":"Tight seccomp profiles (Docker/gVisor/sysbox) that whitelist only a few syscalls and omit the clock_gettime family; chroot/minimal images missing expected clock support; very old or non-standard BSD/macOS builds; CI sandboxes denying time syscalls.","solutions":["Loosen the container/sandbox seccomp profile to allow clock_gettime / clock_gettime64 (and clock_nanosleep) syscalls.","Use a standard libc/runtime image that provides working clock_gettime.","If the platform genuinely lacks the clocks, fall back to the NIO transport (NioEventLoopGroup) instead of kqueue.","On macOS ensure you're on a supported release where clock_gettime is available (10.12+)."],"exampleFix":"// before - hard dependency on kqueue native transport fails to load on a restricted host\nEventLoopGroup group = new KQueueEventLoopGroup();\n\n// after - detect availability and fall back to NIO\nEventLoopGroup group;\ntry {\n    group = new KQueueEventLoopGroup();\n} catch (UnsatisfiedLinkError | ExceptionInInitializerError | RuntimeException e) {\n    group = new NioEventLoopGroup();\n}","handlingStrategy":"fallback","validationCode":"// The error is a native-load failure (stderr + JNI_ERR), not a catchable decode error.\n// Detect it by attempting to create the group and falling back:\nEventLoopGroup group;\ntry {\n    group = new KQueueEventLoopGroup();\n} catch (UnsatisfiedLinkError | ExceptionInInitializerError | RuntimeException e) {\n    group = new NioEventLoopGroup();\n}","typeGuard":null,"tryCatchPattern":"try {\n    return new KQueueEventLoopGroup();\n} catch (UnsatisfiedLinkError | ExceptionInInitializerError e) {\n    log.warn(\"kqueue native transport unavailable, falling back to NIO\", e);\n    return new NioEventLoopGroup();\n}","preventionTips":["Whitelist clock_gettime, clock_gettime64 and clock_nanosleep in your seccomp/container profile when using native transports.","Test the native transport in the exact deployment image (not just dev) — sandbox policies differ.","Always keep an NIO fallback path so a missing native transport doesn't crash the app.","Log native-load failures loudly so a silent stderr-only message is not missed in production."],"tags":["native","netty","kqueue","jni","system-clock","macos","bsd","seccomp"],"backgroundTag":null,"analyzedSha":"70040aacae241e9ba371e758f5b86e470bd77ad1","analyzedAt":"2026-08-14T01:29:15.551Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}