dmtrKovalenko/fff · critical · Error

fff native library not found. Run `npx @ff-labs/fff-node…

Error message

fff native library not found. Run `npx @ff-labs/fff-node download` or build from source with `cargo build --release -p fff-c`

What it means

The fff-bun package's FFI loader could not locate the native Rust shared library (libfff_c) to dlopen. The library scans well-known paths (platform npm packages, dev build dirs, embedded $bunfs path) via findBinary(); if none contains the binary, loadLibrary throws. Most fff APIs lazily call loadLibrary, so any picker/search call fails with this message when the binary is absent.

Solutions

1. Run `npx @ff-labs/fff-node download` to fetch the prebuilt native library for your platform.
2. Build from source: `cargo build --release -p fff-c`, then ensure the output lands in a path findBinary() scans.
3. Verify the platform package (@ff-labs/fff-bin-<platform>) is installed and not excluded by --no-optional or npm/pnpm config.
4. For bun --compile builds, rebuild with the fff-bin package present at compile time (and FFF_LIBC defined on Linux) so the library is embedded in $bunfs.

Example fix

// before: import { findFiles } from 'fff-bun'; findFiles(...)  // throws native library not found
// after
import { isAvailable } from 'fff-bun';
if (!isAvailable()) {
  await $`npx @ff-labs/fff-node download`;
}

import { isAvailable } from 'fff-bun';
if (!isAvailable()) throw new Error('fff native lib missing; run `npx @ff-labs/fff-node download`');

try {
  const results = findFiles(query);
} catch (e) {
  if (String(e.message).includes('native library not found')) {
    execSync('npx @ff-labs/fff-node download');
    return findFiles(query);
  }
  throw e;
}

When it happens

Trigger: Calling any fff-bun API (find_files, search, grep, symbols, ensureLoaded, isAvailable) before the native library exists: the @ff-labs/fff-bin-* platform package was never installed, the project was cloned without running `cargo build --release -p fff-c`, or a bun --compile binary was built without the library embedded (no $bunfs bundled lib and no local build).

Common situations: Fresh installs with optionalDependencies stripped (npm --no-optional, pnpm hoisting issues, yarn resolutions), CI containers lacking the platform package, developers running from a source checkout without building the Rust crate, or Electron/bun single-executable builds that skipped embedding the .so/.dylib/.dll.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• fff native library not found. Run `npx @ff-labs/fff-node…
• FFI returned null pointer
• fff_search_mixed returned null search result
• grep returned null result
• scan progress returned null

AI-assisted analysis of dmtrKovalenko/fff@7f8537e70f (2026-09-10). Data as JSON: /api/errors/bfeedd2391701caf. Report an issue: GitHub.

Appendix: source

Thrown at packages/fff-bun/src/ffi.ts:347

    args: [FFIType.ptr],
    returns: FFIType.void,
  },
} as const;

type FFFLibrary = ReturnType<typeof dlopen<typeof ffiDefinition>>;

let lib: FFFLibrary | null = null;

/**
 * Load the native library
 */
function loadLibrary(): FFFLibrary {
  if (lib) return lib;

  const isEmbedded = embeddedLibPath?.includes("$bunfs") ?? false;
  const binaryPath = isEmbedded ? embeddedLibPath : (findBinary() ?? embeddedLibPath);
  if (!binaryPath) {
    throw new Error(libNotFoundMessage());
  }

  lib = dlopen(binaryPath, ffiDefinition);
  return lib;
}

function libNotFoundMessage(): string {
  if (import.meta.url.includes("$bunfs")) {
    if (process.platform === "linux") {
      return [
        "You are running bun --compile with fff native library which CAN NOT resolve a binary",
        "On Linux the libc must be supplied at compile time so the native lib is bundled.",
        "Rebuild with:",
        "  bun build --compile --define FFF_LIBC='\"gnu\"'  ...   # glibc",
        "  bun build --compile --define FFF_LIBC='\"musl\"' ...   # musl / Alpine",
      ].join("\n");
    }

View on GitHub (pinned to 7f8537e70f)