{"record":{"id":"bfeedd2391701caf","repo":"dmtrKovalenko/fff","slug":"fff-native-library-not-found-run-npx-ff-labs-ff","errorCode":null,"errorMessage":"fff native library not found. Run `npx @ff-labs/fff-node download` or build from source with `cargo build --release -p fff-c`","messagePattern":"fff native library not found\\. Run `npx @ff-labs/fff-node download` or build from source with `cargo build --release -p fff-c`","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/fff-bun/src/ffi.ts","lineNumber":347,"sourceCode":"    args: [FFIType.ptr],\n    returns: FFIType.void,\n  },\n} as const;\n\ntype FFFLibrary = ReturnType<typeof dlopen<typeof ffiDefinition>>;\n\nlet lib: FFFLibrary | null = null;\n\n/**\n * Load the native library\n */\nfunction loadLibrary(): FFFLibrary {\n  if (lib) return lib;\n\n  const isEmbedded = embeddedLibPath?.includes(\"$bunfs\") ?? false;\n  const binaryPath = isEmbedded ? embeddedLibPath : (findBinary() ?? embeddedLibPath);\n  if (!binaryPath) {\n    throw new Error(libNotFoundMessage());\n  }\n\n  lib = dlopen(binaryPath, ffiDefinition);\n  return lib;\n}\n\nfunction libNotFoundMessage(): string {\n  if (import.meta.url.includes(\"$bunfs\")) {\n    if (process.platform === \"linux\") {\n      return [\n        \"You are running bun --compile with fff native library which CAN NOT resolve a binary\",\n        \"On Linux the libc must be supplied at compile time so the native lib is bundled.\",\n        \"Rebuild with:\",\n        \"  bun build --compile --define FFF_LIBC='\\\"gnu\\\"'  ...   # glibc\",\n        \"  bun build --compile --define FFF_LIBC='\\\"musl\\\"' ...   # musl / Alpine\",\n      ].join(\"\\n\");\n    }\n","sourceCodeStart":329,"sourceCodeEnd":365,"githubUrl":"https://github.com/dmtrKovalenko/fff/blob/7f8537e70f0ea1210f9acbbfc4640141105cdc78/packages/fff-bun/src/ffi.ts#L329-L365","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Run `npx @ff-labs/fff-node download` to fetch the prebuilt native library for your platform.","Build from source: `cargo build --release -p fff-c`, then ensure the output lands in a path findBinary() scans.","Verify the platform package (@ff-labs/fff-bin-<platform>) is installed and not excluded by --no-optional or npm/pnpm config.","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."],"exampleFix":"// before: import { findFiles } from 'fff-bun'; findFiles(...)  // throws native library not found\n// after\nimport { isAvailable } from 'fff-bun';\nif (!isAvailable()) {\n  await $`npx @ff-labs/fff-node download`;\n}","handlingStrategy":"fallback","validationCode":"import { isAvailable } from 'fff-bun';\nif (!isAvailable()) throw new Error('fff native lib missing; run `npx @ff-labs/fff-node download`');","typeGuard":null,"tryCatchPattern":"try {\n  const results = findFiles(query);\n} catch (e) {\n  if (String(e.message).includes('native library not found')) {\n    execSync('npx @ff-labs/fff-node download');\n    return findFiles(query);\n  }\n  throw e;\n}","preventionTips":["Call isAvailable()/ensureLoaded() at startup and fail fast with install instructions.","Keep optionalDependencies enabled in npm/pnpm/yarn config.","In CI, install the platform binary explicitly before running tests.","For bun --compile, always build with the fff-bin package present (and FFF_LIBC defined on Linux)."],"tags":["native-library","ffi","bun","installation","missing-binary"],"backgroundTag":"missing-dependency","analyzedSha":"7f8537e70f0ea1210f9acbbfc4640141105cdc78","analyzedAt":"2026-09-10T07:26:53.407Z","contentChangedAt":"2026-09-10T07:26:53.407Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}