apache/druid · warning

Unsatisfied Link error: posix_fadvise failed on file…

Error message

Unsatisfied Link error: posix_fadvise failed on file descriptor [%d], offset [%d]

What it means

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).

Solutions

1. Verify the container/OS matches Druid's supported architectures and glibc-based images
2. Ensure JNA can extract native libraries (mount /tmp as exec, or set -Djna.tmpdir to a writable exec dir)
3. Upgrade the JNA dependency to a version supporting posix_fadvise on your platform
4. Ignore the warning if page-cache skipping is not required; behavior degrades gracefully to normal file I/O

Example fix

// before: Dockerfile with noexec /tmp
// after
ENV JNA_TMPDIR=/opt/jna-tmp
RUN mkdir -p /opt/jna-tmp && chmod 777 /opt/jna-tmp
// and JVM flag: -Djna.tmpdir=/opt/jna-tmp

// Detect native support before relying on cache skipping
boolean nativeOk;
try {
  NativeIO.trySkipCache(fd, 0, 0);
  nativeOk = true;
} catch (Throwable t) {
  nativeOk = false;
}

// The library already degrades gracefully; treat the warning as informational
try {
  NativeIO.trySkipCache(fd, offset, len);
} catch (UnsatisfiedLinkError | UnsupportedOperationException e) {
  // fall back to normal RandomAccessFile behavior
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• failed on syncing fd
• Unable to read /proc/sys/net/core/somaxconn, falling back…

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/0c7fa441e574f8dd. Report an issue: GitHub.

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/java/util/common/io/NativeIO.java:149

   */

  public static void trySkipCache(int fd, long offset, long len)
  {
    if (!initialized || !fadvisePossible || fd < 0) {
      return;
    }
    try {
      // we ignore the return value as this is just best effort to avoid the cache
      posix_fadvise(fd, offset, len, POSIX_FADV_DONTNEED);
    }
    catch (UnsupportedOperationException uoe) {
      log.warn(uoe, "posix_fadvise is not supported");
      fadvisePossible = false;
    }
    catch (UnsatisfiedLinkError ule) {
      // if JNA is unavailable just skipping Direct I/O
      // instance of this class will act like normal RandomAccessFile
      log.warn(ule, "Unsatisfied Link error: posix_fadvise failed on file descriptor [%d], offset [%d]",
          fd, offset);
      fadvisePossible = false;
    }
    catch (Exception e) {
      // This is best effort anyway so lets just log that there was an
      // exception and forget
      log.warn(e, "Unknown exception: posix_fadvise failed on file descriptor [%d], offset [%d]",
          fd, offset);
    }
  }

  /**
   * Sync part of an open file to the file system.
   *
   * @param fd      The file descriptor of the source file.
   * @param offset  The offset within the file.
   * @param nbytes  The number of bytes to be synced.
   * @param flags   Signal how to synchronize

View on GitHub (pinned to 9b90983fd2)