{"record":{"id":"91f1bac79e96da97","repo":"dmtrKovalenko/fff","slug":"fff-create-instance-with-returned-null-handle","errorCode":null,"errorMessage":"fff_create_instance_with returned null handle","messagePattern":"fff_create_instance_with returned null handle","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/fff-node/src/ffi.ts","lineNumber":414,"sourceCode":"    funcName: \"fff_create_instance_with\",\n    retType: DataType.External,\n    paramsType: [FFF_CREATE_OPTIONS_STRUCT],\n    paramsValue: [optsValue],\n    freeResultMemory: false,\n  }) as JsExternal;\n\n  const [structData] = restorePointer({\n    retType: [FFF_RESULT_STRUCT],\n    paramsValue: wrapPointer([rawPtr]),\n  }) as unknown as [FffResultRaw];\n\n  const success = structData.success !== 0;\n\n  try {\n    if (success) {\n      const handle = structData.handle;\n      if (isNullPointer(handle)) {\n        return err(\"fff_create_instance_with returned null handle\");\n      }\n      return { ok: true, value: handle };\n    } else {\n      const errorStr = readCString(structData.error);\n      return err(errorStr || \"Unknown error\");\n    }\n  } finally {\n    freeResult(rawPtr);\n  }\n}\n\n/**\n * Destroy and clean up an instance.\n */\nexport function ffiDestroy(handle: NativeHandle): void {\n  loadLibrary();\n  load({\n    library: LIBRARY_KEY,","sourceCodeStart":396,"sourceCodeEnd":432,"githubUrl":"https://github.com/dmtrKovalenko/fff/blob/7f8537e70f0ea1210f9acbbfc4640141105cdc78/packages/fff-node/src/ffi.ts#L396-L432","documentation":"ffiCreate creates a picker instance via fff_create_instance_with. The native layer reports success (success != 0) but returned a NULL handle, which is an internal inconsistency; the binding converts it to this error rather than returning a bogus handle.","triggerScenarios":"Calling Fff.create()/ffiCreate when the native allocator or instance constructor failed silently — e.g. corrupt global state after a previous crash, or a mismatched native binary that misfills the result struct.","commonSituations":"Loading a stale or wrong-platform prebuilt shared library after upgrading the package without rebuilding; memory pressure causing native allocation failure.","solutions":["Rebuild or reinstall the native library (make build / reinstall package) to match the JS bindings","Free previously created instances and retry — check for leaked handles exhausting native resources","Check platform/arch support for the loaded prebuilt binary"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"const created = Fff.create(opts); if (!created.ok) { throw new Error(`instance creation failed: ${created.error}`); }","preventionTips":["Dispose instances deterministically to avoid handle leaks","Rebuild native binaries after dependency upgrades","Verify platform/arch support before deploying"],"tags":["node","ffi","null-handle"],"backgroundTag":"null-argument","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"}