{"record":{"id":"5207af9be95e6319","repo":"evanw/esbuild","slug":"cannot-use-the-serve-api-in-this-environment","errorCode":null,"errorMessage":"Cannot use the \"serve\" API in this environment","messagePattern":"Cannot use the \"serve\" API in this environment","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/shared/common.ts","lineNumber":1084,"sourceCode":"\n        watch: (options = {}) => new Promise((resolve, reject) => {\n          if (!streamIn.hasFS) throw new Error(`Cannot use the \"watch\" API in this environment`)\n          const keys: OptionKeys = {}\n          const delay = getFlag(options, keys, 'delay', mustBeInteger)\n          checkForInvalidFlags(options, keys, `in watch() call`)\n          const request: protocol.WatchRequest = {\n            command: 'watch',\n            key: buildKey,\n          }\n          if (delay) request.delay = delay\n          sendRequest<protocol.WatchRequest, null>(refs, request, error => {\n            if (error) reject(new Error(error))\n            else resolve(undefined)\n          })\n        }),\n\n        serve: (options = {}) => new Promise((resolve, reject) => {\n          if (!streamIn.hasFS) throw new Error(`Cannot use the \"serve\" API in this environment`)\n          const keys: OptionKeys = {}\n          const port = getFlag(options, keys, 'port', mustBeValidPortNumber)\n          const host = getFlag(options, keys, 'host', mustBeString)\n          const servedir = getFlag(options, keys, 'servedir', mustBeString)\n          const keyfile = getFlag(options, keys, 'keyfile', mustBeString)\n          const certfile = getFlag(options, keys, 'certfile', mustBeString)\n          const fallback = getFlag(options, keys, 'fallback', mustBeString)\n          const cors = getFlag(options, keys, 'cors', mustBeObject)\n          const onRequest = getFlag(options, keys, 'onRequest', mustBeFunction)\n          checkForInvalidFlags(options, keys, `in serve() call`)\n\n          const request: protocol.ServeRequest = {\n            command: 'serve',\n            key: buildKey,\n            onRequest: !!onRequest,\n          }\n          if (port !== void 0) request.port = port\n          if (host !== void 0) request.host = host","sourceCodeStart":1066,"sourceCodeEnd":1102,"githubUrl":"https://github.com/evanw/esbuild/blob/f6058f8364fe7ab91ca57a83e02577ed74c9cae4/lib/shared/common.ts#L1066-L1102","documentation":"Thrown by the context's `serve()` method (lib/shared/common.ts:1084) when `streamIn.hasFS` is false. The serve API starts a local HTTP server that serves built files and a directory of static assets, which requires filesystem access. It is therefore disabled in the browser/WASM build (`hasFS: false`).","triggerScenarios":"Calling `context.serve({ port, servedir, ... })` on a context created through the browser/WASM esbuild API.","commonSituations":"Reusing a Node dev-server config (that calls `serve()`) with the WASM build; building an in-browser bundler playground and attempting to start esbuild's built-in server.","solutions":["Use the native node esbuild package so `serve()` is available (`hasFS` is true).","In the browser, run your own HTTP server or serve the `outputFiles` from the build result through your own hosting layer.","Gate the `serve()` call behind a Node-only code path."],"exampleFix":"// before (browser/wasm)\nconst ctx = await esbuild.context(opts);\nawait ctx.serve({ servedir: '.', port: 8000 });\n// after — host outputs yourself\nconst result = await esbuild.build({ ...opts, write: false });\n// serve result.outputFiles via your own server/handler","handlingStrategy":"validation","validationCode":"const canServe = typeof process !== 'undefined' && !!process.versions && !!process.versions.node;\nif (canServe) await ctx.serve(serveOpts); else { /* host outputs yourself */ }","typeGuard":"function supportsServe(): boolean {\n  return typeof process !== 'undefined' && !!process.versions && !!process.versions.node;\n}","tryCatchPattern":null,"preventionTips":["Run your own HTTP server for browser contexts.","Gang serve() behind a Node-only code path to avoid importing it in the browser bundle."],"tags":["environment","filesystem","browser","wasm","serve","dev-server"],"backgroundTag":null,"analyzedSha":"f6058f8364fe7ab91ca57a83e02577ed74c9cae4","analyzedAt":"2026-08-09T18:37:22.223Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}