dmtrKovalenko/fff · error

fff_create_instance_with returned null handle

Error message

fff_create_instance_with returned null handle

What it means

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.

Solutions

1. Rebuild or reinstall the native library (make build / reinstall package) to match the JS bindings
2. Free previously created instances and retry — check for leaked handles exhausting native resources
3. Check platform/arch support for the loaded prebuilt binary

const created = Fff.create(opts); if (!created.ok) { throw new Error(`instance creation failed: ${created.error}`); }

When it happens

Trigger: 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.

Common situations: Loading a stale or wrong-platform prebuilt shared library after upgrading the package without rebuilding; memory pressure causing native allocation failure.

Related errors

• grep returned null result
• fff_search returned null search result
• fff native library not found. Run `npx @ff-labs/fff-node…
• Unknown error
• fff native library not found. Run `npx @ff-labs/fff-node…

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

Appendix: source

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

    funcName: "fff_create_instance_with",
    retType: DataType.External,
    paramsType: [FFF_CREATE_OPTIONS_STRUCT],
    paramsValue: [optsValue],
    freeResultMemory: false,
  }) as JsExternal;

  const [structData] = restorePointer({
    retType: [FFF_RESULT_STRUCT],
    paramsValue: wrapPointer([rawPtr]),
  }) as unknown as [FffResultRaw];

  const success = structData.success !== 0;

  try {
    if (success) {
      const handle = structData.handle;
      if (isNullPointer(handle)) {
        return err("fff_create_instance_with returned null handle");
      }
      return { ok: true, value: handle };
    } else {
      const errorStr = readCString(structData.error);
      return err(errorStr || "Unknown error");
    }
  } finally {
    freeResult(rawPtr);
  }
}

/**
 * Destroy and clean up an instance.
 */
export function ffiDestroy(handle: NativeHandle): void {
  loadLibrary();
  load({
    library: LIBRARY_KEY,

View on GitHub (pinned to 7f8537e70f)