krisk/Fuse · error · Error

FuseWorker: unable to resolve the worker script URL automati

Error message

FuseWorker: unable to resolve the worker script URL automatically; pass workerOptions.workerUrl explicitly.

What it means

Thrown by resolveDefaultWorkerUrl (invoked from the FuseWorker constructor) when every automatic strategy for locating the fuse.worker.mjs script fails: the CJS browser base captured at load time is absent and constructing the URL from import.meta.url throws. This happens in non-standard environments — bundlers that strip import.meta, sandboxed/no-document contexts, or unusual module formats — where the library cannot infer where the worker asset was emitted.

Source

Thrown at src/workers/FuseWorker.ts:76

  // script, NOT via import.meta.url: its CJS rewrite (require('url')/__filename)
  // can be polyfilled by browser bundlers (webpack/browserify) to a virtual path,
  // which would silently win over the real script location. So when this is the
  // CJS output and a document is present (browser-CJS), prefer the captured base.
  // This matches the old Rollup CJS shim, which always preferred document in the
  // browser. The ESM build keeps the import.meta.url literal below so bundlers
  // detect + rewrite the worker asset (browser-ESM) and Node resolves it natively.
  if (__WORKER_IS_CJS__ && browserWorkerBase !== undefined) {
    return new URL('./fuse.worker.mjs', browserWorkerBase)
  }
  try {
    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
    // @ts-ignore -- import.meta.url is provided by the bundler per output format
    return new URL('./fuse.worker.mjs', import.meta.url)
  } catch {
    if (browserWorkerBase !== undefined) {
      return new URL('./fuse.worker.mjs', browserWorkerBase)
    }
    throw new Error(
      'FuseWorker: unable to resolve the worker script URL automatically; ' +
        'pass workerOptions.workerUrl explicitly.'
    )
  }
}

export default class FuseWorker<T> {
  private _options: IFuseOptions<T>
  private _workerOptions: FuseWorkerOptions
  private _docs: T[]
  private _shards: Shard[] | null = null
  private _addCursor = 0
  private _initPromise: Promise<void> | null = null
  private _pending: Map<number, PendingCall> = new Map()
  private _nextId = 0
  private _workerUrl: string | URL

  constructor(

View on GitHub (pinned to edf2fb608e)

Solutions

1. Pass the URL explicitly: new FuseWorker(docs, options, { workerUrl: new URL('./fuse.worker.mjs', import.meta.url) })
2. Copy the fuse.worker.mjs asset next to your bundle (or emit it via your bundler's worker support) so the default resolution can find it
3. Check that the environment provides either import.meta.url (ESM) or a document base (browser CJS); if not, workerUrl is mandatory
4. Serve the page over http(s) — file:// URLs cannot construct valid worker script URLs in most browsers

When it happens

Trigger: Thrown at src/workers/FuseWorker.ts:76 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of krisk/Fuse@edf2fb608e (2026-09-02). Data as JSON: /api/errors/af233333f73f5c88. Report an issue: GitHub.