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-node package loads its native library through koffi's open(); before that, findBinary() must locate libfff_c on disk. When no candidate path exists, loadLibrary throws this message, and since every FFI entry point (create/destroy, search/grep parsing, result accessors) routes through it, all API calls fail.

Solutions

1. Run `npx @ff-labs/fff-node download` to install the prebuilt native library.
2. Build from source: `cargo build --release -p fff-c` and ensure the artifact is in a scanned location (e.g. the expected target/release path).
3. Reinstall dependencies without omitting optional packages: `npm install` (drop --omit=optional / --no-optional).
4. Confirm the @ff-labs/fff-bin-<platform> package for your triple is resolvable from your registry.

Example fix

// before: const picker = createFilePicker(dir); // throws at loadLibrary
// after
import { existsSync } from 'fs';
// ensure binary exists before use
if (!existsSync(require('fff-node/platform').getLibPath?.() ?? '')) {
  await downloadFffBinary(); // npx @ff-labs/fff-node download
}

try { require('fff-node').ensureLoaded?.(); } catch { /* trigger download */ }

try {
  const picker = createFilePicker(dir);
} catch (e) {
  if (String(e.message).includes('fff native library not found')) {
    execSync('npx @ff-labs/fff-node download', { stdio: 'inherit' });
    return createFilePicker(dir);
  }
  throw e;
}

When it happens

Trigger: Calling any fff-node API when the native library is missing: fresh `npm install` where the @ff-labs/fff-bin-* optional dependency failed or was skipped, a source checkout without `cargo build --release -p fff-c`, or a machine whose platform has no prebuilt package.

Common situations: npm installed with --omit=optional, pnpm/yarn optional-dependency bugs, Alpine Docker images getting the wrong libc variant, corporate registries missing the platform package, or developers cloning the monorepo and running tests before building the Rust crate.

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…
• Unknown error
• fff_create_instance_with returned null handle
• grep returned null result
• fff_search returned null search result

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

Appendix: source

Thrown at packages/fff-node/src/ffi.ts:144

  int_value: DataType.I64,
};

interface FffResultRaw {
  success: number;
  error: JsExternal;
  handle: JsExternal;
  int_value: number;
}

/**
 * Load the native library using ffi-rs
 */
function loadLibrary(): void {
  if (isLoaded) return;

  const binaryPath = findBinary();
  if (!binaryPath) {
    throw new Error(
      "fff native library not found. Run `npx @ff-labs/fff-node download` or build from source with `cargo build --release -p fff-c`",
    );
  }

  open({ library: LIBRARY_KEY, path: binaryPath });
  isLoaded = true;
}

/**
 * Convert snake_case keys to camelCase recursively
 */
function snakeToCamel(obj: unknown): unknown {
  if (obj === null || obj === undefined) return obj;
  if (typeof obj !== "object") return obj;
  if (Array.isArray(obj)) return obj.map(snakeToCamel);

  const result: Record<string, unknown> = {};
  for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {

View on GitHub (pinned to 7f8537e70f)