{"record":{"id":"cb09308b25be5e3a","repo":"evanw/esbuild","slug":"you-need-to-wait-for-the-promise-returned-from-in","errorCode":null,"errorMessage":"You need to wait for the promise returned from \"initialize\" to be resolved before calling this","messagePattern":"You need to wait for the promise returned from \"initialize\" to be resolved before calling this","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/npm/browser.ts","lineNumber":67,"sourceCode":"  if (stopService) stopService()\n  return Promise.resolve()\n}\n\ninterface Service {\n  build: typeof types.build\n  context: typeof types.context\n  transform: typeof types.transform\n  formatMessages: typeof types.formatMessages\n  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","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/evanw/esbuild/blob/f6058f8364fe7ab91ca57a83e02577ed74c9cae4/lib/npm/browser.ts#L49-L85","documentation":"In the browser build (lib/npm/browser.ts:65-69), ensureServiceIsRunning() throws this specific message when initialize() has been called (so initializePromise is set) but has not yet resolved (longLivedService is still undefined), and an API method like build/transform is invoked in between. esbuild requires the WASM service to be fully booted before any call because WebAssembly instantiation is asynchronous.","triggerScenarios":"Calling esbuild.build(...)/transform(...)/etc. immediately after esbuild.initialize({...}) without awaiting the promise initialize returns, while running the browser/WASM build.","commonSituations":"Forgetting to await initialize at module top level; sequential statements in non-async code that call initialize then build; refactoring from node (where the service auto-starts) to browser without adding the await.","solutions":["Await the promise returned by initialize before any other esbuild call.","Chain subsequent calls in a .then() on initialize if top-level await is unavailable.","Centralize initialization in an async bootstrap function that all esbuild usage goes through."],"exampleFix":"// before\nesbuild.initialize({ wasmURL: '/esbuild.wasm' })\nesbuild.build({ entryPoints: ['a.ts'] })  // throws\n\n// after\nawait esbuild.initialize({ wasmURL: '/esbuild.wasm' })\nawait esbuild.build({ entryPoints: ['a.ts'] })","handlingStrategy":"validation","validationCode":"// Track initialization state and never call APIs before it resolves.\nlet ready: Promise<void>\n\nasync function boot() {\n  ready = esbuild.initialize({ wasmURL: '/esbuild.wasm' })\n  await ready\n}\n\nasync function safeBuild(opts) {\n  if (!ready) throw new Error('esbuild not initialized')\n  await ready                       // ensure the service is up\n  return esbuild.build(opts)\n}","typeGuard":null,"tryCatchPattern":"// If you cannot await statically, catch and retry after initialize resolves.\ntry {\n  await esbuild.build(opts)\n} catch (e) {\n  if (/wait for the promise returned from \"initialize\"/.test(String(e?.message))) {\n    await esbuildInitializePromise      // the promise from initialize()\n    await esbuild.build(opts)\n  } else {\n    throw e\n  }\n}","preventionTips":["Always `await esbuild.initialize(...)` as the first esbuild operation.","Route all esbuild calls through a single async bootstrap that guarantees readiness.","Treat initialize() like an async constructor: nothing else may run until it resolves."],"tags":["browser","async","initialization","wasm","ordering"],"backgroundTag":null,"analyzedSha":"f6058f8364fe7ab91ca57a83e02577ed74c9cae4","analyzedAt":"2026-08-09T18:37:22.223Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}