evanw/esbuild · error · Error

The "analyzeMetafileSync" API only works in node

Error message

The "analyzeMetafileSync" API only works in node

What it means

The browser entry of esbuild (lib/npm/browser.ts) defines analyzeMetafileSync as a stub that always throws. Metafile analysis in the browser goes through the async WebAssembly service, so no synchronous form is offered.

Solutions

1. Use esbuild.analyzeMetafile(...) and await the returned promise.
2. Perform the analysis ahead of time in a node build step and ship the result.
3. Use the native esbuild package under node if a synchronous call is mandatory.

Example fix

// before
const report = esbuild.analyzeMetafileSync(metafile)

// after
const report = await esbuild.analyzeMetafile(metafile)

// Choose the async analyze API in browser-capable code.
const isBrowserBuild =
  typeof window !== 'undefined' && typeof window.document !== 'undefined'

const report = isBrowserBuild
  ? await esbuild.analyzeMetafile(metafile)
  : esbuild.analyzeMetafileSync(metafile)

When it happens

Trigger: Application code calls esbuild.analyzeMetafileSync(metafile, options) while the active module is the browser build (esbuild-wasm or the package 'browser' field).

Common situations: Bundle-size analysis dashboards running in the browser that reused node sample code; build-report tooling shared between node and web.

Related errors

• The "buildSync" API only works in node
• The "formatMessagesSync" API only works in node
• The "transformSync" API only works in node
• You need to wait for the promise returned from "initialize"…
• Cannot use the "serve" API in this environment

AI-assisted analysis of evanw/esbuild@f6058f8364 (2026-08-09). Data as JSON: /api/errors/ca37eaacbd0490e9. Report an issue: GitHub.

Appendix: source

Thrown at lib/npm/browser.ts:45

  ensureServiceIsRunning().formatMessages(messages, options)

export const analyzeMetafile: typeof types.analyzeMetafile = (metafile, options) =>
  ensureServiceIsRunning().analyzeMetafile(metafile, options)

export const buildSync: typeof types.buildSync = () => {
  throw new Error(`The "buildSync" API only works in node`)
}

export const transformSync: typeof types.transformSync = () => {
  throw new Error(`The "transformSync" API only works in node`)
}

export const formatMessagesSync: typeof types.formatMessagesSync = () => {
  throw new Error(`The "formatMessagesSync" API only works in node`)
}

export const analyzeMetafileSync: typeof types.analyzeMetafileSync = () => {
  throw new Error(`The "analyzeMetafileSync" API only works in node`)
}

export const stop = () => {
  if (stopService) stopService()
  return Promise.resolve()
}

interface Service {
  build: typeof types.build
  context: typeof types.context
  transform: typeof types.transform
  formatMessages: typeof types.formatMessages
  analyzeMetafile: typeof types.analyzeMetafile
}

let initializePromise: Promise<void> | undefined
let stopService: (() => void) | undefined
let longLivedService: Service | undefined

View on GitHub (pinned to f6058f8364)