{"id":"56cfbabab42509f2","repo":"evanw/esbuild","slug":"must-provide-either-the-wasmurl-option-or-the-w","errorCode":null,"errorMessage":"Must provide either the \"wasmURL\" option or the \"wasmModule\" option","messagePattern":"Must provide either the \"wasmURL\" option or the \"wasmModule\" option","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/npm/browser.ts","lineNumber":76,"sourceCode":"  analyzeMetafile: typeof types.analyzeMetafile\n}\n\nlet initializePromise: Promise<void> | undefined\nlet stopService: (() => void) | undefined\nlet longLivedService: Service | undefined\n\nlet ensureServiceIsRunning = (): Service => {\n  if (longLivedService) return longLivedService\n  if (initializePromise) throw new Error('You need to wait for the promise returned from \"initialize\" to be resolved before calling this')\n  throw new Error('You need to call \"initialize\" before calling this')\n}\n\nexport const initialize: typeof types.initialize = options => {\n  options = common.validateInitializeOptions(options || {})\n  let wasmURL = options.wasmURL\n  let wasmModule = options.wasmModule\n  let useWorker = options.worker !== false\n  if (!wasmURL && !wasmModule) throw new Error('Must provide either the \"wasmURL\" option or the \"wasmModule\" option')\n  if (initializePromise) throw new Error('Cannot call \"initialize\" more than once')\n  initializePromise = startRunningService(wasmURL || '', wasmModule, useWorker)\n  initializePromise.catch(() => {\n    // Let the caller try again if this fails\n    initializePromise = void 0\n  })\n  return initializePromise\n}\n\nconst startRunningService = async (wasmURL: string | URL, wasmModule: WebAssembly.Module | undefined, useWorker: boolean): Promise<void> => {\n  let worker: {\n    onmessage: ((event: any) => void) | null\n    postMessage: (data: Uint8Array | ArrayBuffer | WebAssembly.Module) => void\n    terminate: () => void\n  }\n\n  let rejectAllWith: (error: unknown) => void\n  const rejectAllPromise = new Promise(resolve => rejectAllWith = resolve)","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/evanw/esbuild/blob/6ff1d8b0d8c134e867a397eef39702a223ebef9e/lib/npm/browser.ts#L58-L94","documentation":"The browser `initialize` (`lib/npm/browser.ts:76`) requires the caller to point at the WebAssembly binary, because the browser build has no native executable and no filesystem. You must supply either `wasmURL` (a URL esbuild will fetch) or `wasmModule` (a pre-instantiated `WebAssembly.Module`). Without one, esbuild cannot boot the Go runtime that powers the API.","triggerScenarios":"Calling `esbuild.initialize()` (or `initialize({})`) with neither `wasmURL` nor `wasmModule` in the browser/esbuild-wasm context.","commonSituations":"Copy-pasted initialize code missing the option; using a CDN or bundler that already provides the wasm module but forgetting to pass it; migrating from esbuild (Node) to esbuild-wasm without adding the option; bundlers that tree-shake the option object.","solutions":["Pass `wasmURL` pointing at the esbuild.wasm asset: `initialize({ wasmURL: '/esbuild.wasm' })`.","If your bundler supports importing wasm as a Module, pass `wasmModule: await WebAssembly.compile(await fetch(url).then(r => r.arrayBuffer()))`.","For bundlers like Vite, use `?url` import suffix to get the asset URL: `import wasmURL from 'esbuild-wasm/esbuild.wasm?url'`.","Ensure the option object isn't being mutated or stripped by build tooling."],"exampleFix":"// before\nimport * as esbuild from 'esbuild-wasm'\nawait esbuild.initialize({})\n\n// after\nimport wasmURL from 'esbuild-wasm/esbuild.wasm?url'\nawait esbuild.initialize({ wasmURL })","handlingStrategy":"validation","validationCode":"function buildInit(opts: { wasmURL?: string; wasmModule?: WebAssembly.Module }) {\n  if (!opts.wasmURL && !opts.wasmModule) {\n    throw new Error('initialize requires wasmURL or wasmModule in the browser')\n  }\n  return esbuild.initialize(opts)\n}","typeGuard":"function hasWasmSource(o: { wasmURL?: unknown; wasmModule?: unknown }): boolean {\n  return typeof o.wasmURL === 'string' || o.wasmURL instanceof URL || o.wasmModule instanceof WebAssembly.Module\n}","tryCatchPattern":"try {\n  await esbuild.initialize(opts)\n} catch (e) {\n  if (/Must provide either/.test((e as Error).message)) {\n    await esbuild.initialize({ ...opts, wasmURL: defaultWasmURL })\n    return\n  }\n  throw e\n}","preventionTips":["Always pass wasmURL (or wasmModule) in browser/esbuild-wasm initialize calls.","Use bundler asset imports (`?url`) to get a correct wasmURL.","Assert in a helper that one of the two options is present before calling initialize.","Document the wasmURL requirement prominently in your project README."],"tags":["browser","wasm","initialize","configuration"],"analyzedSha":"6ff1d8b0d8c134e867a397eef39702a223ebef9e","analyzedAt":"2026-08-03T19:42:38.433Z","schemaVersion":2}