What causes "scan progress returned null" in dmtrKovalenko/fff?

Only poll scan progress after triggering a scan/rescan and confirming the instance is alive.

scan progress returned null

Error message

scan progress returned null

What it means

fff_get_scan_progress returned a null handle for the scan-progress struct even though the envelope reported success. The FFI layer cannot read FffScanProgress without a valid pointer, so it errors with "scan progress returned null". This means the native side has no progress object to hand out, typically because scanning has not started or the state was reset.

Solutions

Only poll scan progress after triggering a scan/rescan and confirming the instance is alive.
Treat this error as "no progress available yet" and retry after a short delay.
Rebuild/upgrade the native binary if it predates scan-progress support.
If it persists on an active scan, report a bug with the native library version.

Example fix

// before
const p = finder.getScanProgress();
if (!p.ok) throw new Error(p.error);
// after
const p = finder.getScanProgress();
if (!p.ok) {
  if (p.error.includes('null')) return { scanned: 0, total: 0, done: false }; // no scan yet
  throw new Error(p.error);
}

Defensive patterns

Strategy: fallback

Validate before calling

// only poll after a scan was requested and the finder is alive
if (!finder.isAlive() || !scanRequested) skipProgressPoll();

Type guard

function hasProgress(p: Result<ScanProgress>): p is { ok: true; value: ScanProgress } { return p.ok; }

Try / catch

const p = finder.getScanProgress();
const progress = p.ok ? p.value : { scanned: 0, total: 0, done: false }; // graceful default

Prevention

Start polling only after triggering a scan.
Treat missing progress as 'not started' rather than a hard failure.
Match native binary and binding versions.
Debounce progress polling to avoid racing state resets.

When it happens

Trigger: Calling FileFinder.getScanProgress when no scan has been initiated for the instance, after a rescan reset cleared progress state, or when the native binary fails to allocate the FffScanProgress struct.

Common situations: Polling progress right after construction before the background scan spawned; polling after the picker/index was reinitialized; version-mismatched native binary lacking progress support.

Related errors

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

Appendix: source

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

}

/**
 * Get scan progress.
 */
export function ffiGetScanProgress(handle: NativeHandle): Result<{
  scannedFilesCount: number;
  isScanning: boolean;
  isWatcherReady: boolean;
  isWarmupComplete: boolean;
}> {
  loadLibrary();
  const res = readResultEnvelope("fff_get_scan_progress", [DataType.External], [handle]);
  if ("ok" in res) return res;

  const handlePtr = res.struct.handle;
  freeResult(res.rawPtr);

  if (isNullPointer(handlePtr)) return err("scan progress returned null");

  const [sp] = restorePointer({
    retType: [FFF_SCAN_PROGRESS_STRUCT],
    paramsValue: wrapPointer([handlePtr]),
  }) as unknown as [FffScanProgressRaw];

  const result = {
    scannedFilesCount: Number(sp.scanned_files_count),
    isScanning: sp.is_scanning !== 0,
    isWatcherReady: sp.is_watcher_ready !== 0,
    isWarmupComplete: sp.is_warmup_complete !== 0,
  };

  // Free native scan progress
  load({
    library: LIBRARY_KEY,
    funcName: "fff_free_scan_progress",
    retType: DataType.Void,

View on GitHub (pinned to 7f8537e70f)