{"record":{"id":"0c7fa441e574f8dd","repo":"apache/druid","slug":"unsatisfied-link-error-posix-fadvise-failed-on-fi","errorCode":null,"errorMessage":"Unsatisfied Link error: posix_fadvise failed on file descriptor [%d], offset [%d]","messagePattern":"Unsatisfied Link error: posix_fadvise failed on file descriptor \\[(.+?)\\], offset \\[(.+?)\\]","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"processing/src/main/java/org/apache/druid/java/util/common/io/NativeIO.java","lineNumber":149,"sourceCode":"   */\n\n  public static void trySkipCache(int fd, long offset, long len)\n  {\n    if (!initialized || !fadvisePossible || fd < 0) {\n      return;\n    }\n    try {\n      // we ignore the return value as this is just best effort to avoid the cache\n      posix_fadvise(fd, offset, len, POSIX_FADV_DONTNEED);\n    }\n    catch (UnsupportedOperationException uoe) {\n      log.warn(uoe, \"posix_fadvise is not supported\");\n      fadvisePossible = false;\n    }\n    catch (UnsatisfiedLinkError ule) {\n      // if JNA is unavailable just skipping Direct I/O\n      // instance of this class will act like normal RandomAccessFile\n      log.warn(ule, \"Unsatisfied Link error: posix_fadvise failed on file descriptor [%d], offset [%d]\",\n          fd, offset);\n      fadvisePossible = false;\n    }\n    catch (Exception e) {\n      // This is best effort anyway so lets just log that there was an\n      // exception and forget\n      log.warn(e, \"Unknown exception: posix_fadvise failed on file descriptor [%d], offset [%d]\",\n          fd, offset);\n    }\n  }\n\n  /**\n   * Sync part of an open file to the file system.\n   *\n   * @param fd      The file descriptor of the source file.\n   * @param offset  The offset within the file.\n   * @param nbytes  The number of bytes to be synced.\n   * @param flags   Signal how to synchronize","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/processing/src/main/java/org/apache/druid/java/util/common/io/NativeIO.java#L131-L167","documentation":"NativeIO.trySkipCache uses JNA to call posix_fadvise(POSIX_FADV_DONTNEED) on a file descriptor to drop pages from the OS page cache. If the JNA native binding cannot be linked on the current platform, an UnsatisfiedLinkError is caught and logged as a warning; the class then acts as a normal RandomAccessFile and never retries fadvise (fadvisePossible=false).","triggerScenarios":"First call to trySkipCache on a platform where the JNA-posixadvise native library is unavailable: wrong architecture, missing native lib, or JNA unable to load its bundled natives.","commonSituations":"Running Druid on Alpine/musl or non-x86_64/aarch64 platforms where the packaged native library doesn't load; stripped-down container images missing JNA's temp-dir extraction permissions (noexec /tmp); older JNA versions lacking posix_fadvise support.","solutions":["Verify the container/OS matches Druid's supported architectures and glibc-based images","Ensure JNA can extract native libraries (mount /tmp as exec, or set -Djna.tmpdir to a writable exec dir)","Upgrade the JNA dependency to a version supporting posix_fadvise on your platform","Ignore the warning if page-cache skipping is not required; behavior degrades gracefully to normal file I/O"],"exampleFix":"// before: Dockerfile with noexec /tmp\n// after\nENV JNA_TMPDIR=/opt/jna-tmp\nRUN mkdir -p /opt/jna-tmp && chmod 777 /opt/jna-tmp\n// and JVM flag: -Djna.tmpdir=/opt/jna-tmp","handlingStrategy":"fallback","validationCode":"// Detect native support before relying on cache skipping\nboolean nativeOk;\ntry {\n  NativeIO.trySkipCache(fd, 0, 0);\n  nativeOk = true;\n} catch (Throwable t) {\n  nativeOk = false;\n}","typeGuard":null,"tryCatchPattern":"// The library already degrades gracefully; treat the warning as informational\ntry {\n  NativeIO.trySkipCache(fd, offset, len);\n} catch (UnsatisfiedLinkError | UnsupportedOperationException e) {\n  // fall back to normal RandomAccessFile behavior\n}","preventionTips":["Use glibc-based images on x86_64 or aarch64 that match Druid's native library set","Give JNA an executable temp directory (-Djna.tmpdir) so natives can extract","Keep the JNA dependency current to pick up new platform bindings","Accept the degraded path: cache skipping is an optimization, not a correctness feature"],"tags":["native","jna","posix","page-cache","linux"],"backgroundTag":"unsupported-platform","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}