What causes "Unknown error" in dmtrKovalenko/fff?

Log/inspect the input arguments to the failing FFI call to find the invalid input

Unknown error

Error message

Unknown error

What it means

readResultEnvelope converts the native FffResult envelope into a JS Result. When envelope.success is 0 it reads the native error string; if that string is empty or NULL it cannot recover a message and falls back to the generic 'Unknown error'.

Solutions

Log/inspect the input arguments to the failing FFI call to find the invalid input
Rebuild the native library so native and JS bindings match (make build)
Report upstream: the native side should always set an error message on failure

Defensive patterns

Strategy: try-catch

Validate before calling

null

Try / catch

const res = envelopeCall(...); if (!res.ok) { console.error('FFI failed:', res.error); /* fallback or rethrow with context */ }

Prevention

Keep the native binary and JS bindings on the same version
Log inputs to FFI calls to compensate for missing native error strings
Rebuild after upgrading the package

When it happens

Trigger: Any FFI call routed through readResultEnvelope whose native side failed without setting the error field, or the error pointer is null/unreadable.

Common situations: Calling a native function with arguments it does not validate (e.g. empty buffers), library/native binary version mismatch where error strings are not populated, or a genuinely empty error from the Rust side.

Related errors

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

Appendix: source

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

  }
}

/**
 * Read the FffResult envelope from a raw call. Returns the parsed struct + raw pointer.
 * On error, frees the result and returns a Result error.
 */
function readResultEnvelope(
  funcName: string,
  paramsType: FieldType[],
  paramsValue: unknown[],
): { rawPtr: JsExternal; struct: FffResultRaw } | Result<never> {
  loadLibrary();
  const { rawPtr, struct: structData } = callRaw(funcName, paramsType, paramsValue);

  if (structData.success === 0) {
    const errorStr = readCString(structData.error);
    freeResult(rawPtr);
    return err(errorStr || "Unknown error");
  }

  return { rawPtr, struct: structData };
}

/** Call a function returning FffResult with void payload. */
function callVoidResult(
  funcName: string,
  paramsType: FieldType[],
  paramsValue: unknown[],
): Result<void> {
  const res = readResultEnvelope(funcName, paramsType, paramsValue);
  if ("ok" in res) return res;
  freeResult(res.rawPtr);
  return { ok: true, value: undefined };
}

/** Call a function returning FffResult with int_value payload. */

View on GitHub (pinned to 7f8537e70f)