{"record":{"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/f6058f8364fe7ab91ca57a83e02577ed74c9cae4/lib/npm/browser.ts#L58-L94","documentation":"The browser build's initialize() (lib/npm/browser.ts:76) requires the caller to explicitly tell esbuild where the WebAssembly module is, since a browser has no filesystem to locate it automatically. If neither wasmURL nor wasmModule is supplied, it throws. These options are mutually sufficient: provide at least one.","triggerScenarios":"Calling esbuild.initialize() (or initialize({}) / initialize({ worker: true })) in the browser build without specifying where esbuild.wasm lives or supplying a precompiled WebAssembly.Module.","commonSituations":"Adapting a minimal example that omitted the wasmURL; serving the wasm from a CDN or asset path but forgetting to pass the option; intending to reuse a fetched module but passing undefined.","solutions":["Provide wasmURL pointing to your served esbuild.wasm (absolute URL, relative URL, or CDN URL).","Alternatively, pass a precompiled WebAssembly.Module via wasmModule (e.g. fetch+compile once and reuse).","Ensure the wasmURL resolves to the same esbuild version as the JS package to avoid protocol/ABI mismatch."],"exampleFix":"// before\nawait esbuild.initialize({})\n\n// after\nawait esbuild.initialize({ wasmURL: '/node_modules/esbuild-wasm/esbuild.wasm' })","handlingStrategy":"validation","validationCode":"// Validate required wasm options before calling initialize.\nfunction makeInitOptions(wasmURL?: string, wasmModule?: WebAssembly.Module) {\n  if (!wasmURL && !wasmModule) {\n    throw new Error('Initialize requires wasmURL or wasmModule')\n  }\n  return { wasmURL, wasmModule }\n}\n\nawait esbuild.initialize(makeInitOptions('/esbuild.wasm'))","typeGuard":"// Narrow an options object to a valid browser initialize payload.\ntype InitOpts = { wasmURL?: string; wasmModule?: WebAssembly.Module }\nfunction hasWasmSource(o: InitOpts): o is { wasmURL: string } | { wasmModule: WebAssembly.Module } {\n  return typeof o.wasmURL === 'string' || o.wasmModule instanceof WebAssembly.Module\n}","tryCatchPattern":null,"preventionTips":["Always supply wasmURL (or wasmModule) when calling initialize in the browser.","Keep the esbuild.wasm URL in a single config constant reused everywhere.","Pin the wasm asset to the same esbuild version as the JS package."],"tags":["browser","initialization","wasm","validation"],"backgroundTag":null,"analyzedSha":"f6058f8364fe7ab91ca57a83e02577ed74c9cae4","analyzedAt":"2026-08-09T18:37:22.223Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}