{"record":{"id":"a39cbb4f585fb791","repo":"dmtrKovalenko/fff","slug":"fff-native-library-not-found-run-npx-ff-labs-ff-a39cbb","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-node/src/ffi.ts","lineNumber":144,"sourceCode":"  int_value: DataType.I64,\n};\n\ninterface FffResultRaw {\n  success: number;\n  error: JsExternal;\n  handle: JsExternal;\n  int_value: number;\n}\n\n/**\n * Load the native library using ffi-rs\n */\nfunction loadLibrary(): void {\n  if (isLoaded) return;\n\n  const binaryPath = findBinary();\n  if (!binaryPath) {\n    throw new Error(\n      \"fff native library not found. Run `npx @ff-labs/fff-node download` or build from source with `cargo build --release -p fff-c`\",\n    );\n  }\n\n  open({ library: LIBRARY_KEY, path: binaryPath });\n  isLoaded = true;\n}\n\n/**\n * Convert snake_case keys to camelCase recursively\n */\nfunction snakeToCamel(obj: unknown): unknown {\n  if (obj === null || obj === undefined) return obj;\n  if (typeof obj !== \"object\") return obj;\n  if (Array.isArray(obj)) return obj.map(snakeToCamel);\n\n  const result: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {","sourceCodeStart":126,"sourceCodeEnd":162,"githubUrl":"https://github.com/dmtrKovalenko/fff/blob/7f8537e70f0ea1210f9acbbfc4640141105cdc78/packages/fff-node/src/ffi.ts#L126-L162","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run `npx @ff-labs/fff-node download` to install the prebuilt native library.","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).","Reinstall dependencies without omitting optional packages: `npm install` (drop --omit=optional / --no-optional).","Confirm the @ff-labs/fff-bin-<platform> package for your triple is resolvable from your registry."],"exampleFix":"// before: const picker = createFilePicker(dir); // throws at loadLibrary\n// after\nimport { existsSync } from 'fs';\n// ensure binary exists before use\nif (!existsSync(require('fff-node/platform').getLibPath?.() ?? '')) {\n  await downloadFffBinary(); // npx @ff-labs/fff-node download\n}","handlingStrategy":"try-catch","validationCode":"try { require('fff-node').ensureLoaded?.(); } catch { /* trigger download */ }","typeGuard":null,"tryCatchPattern":"try {\n  const picker = createFilePicker(dir);\n} catch (e) {\n  if (String(e.message).includes('fff native library not found')) {\n    execSync('npx @ff-labs/fff-node download', { stdio: 'inherit' });\n    return createFilePicker(dir);\n  }\n  throw e;\n}","preventionTips":["Run `npx @ff-labs/fff-node download` in postinstall or CI setup.","Do not install with --omit=optional / --no-optional.","Confirm the correct libc variant (gnu vs musl) for Alpine images.","Build the Rust crate when developing in the monorepo."],"tags":["native-library","ffi","node","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"}