evanw/esbuild · error

The "serve" API is not supported when using WebAssembly

Error message

The "serve" API is not supported when using WebAssembly

What it means

Returned by the WebAssembly build of esbuild's API (pkg/api/serve_wasm.go, compiled with //go:build js && wasm). The serve API spins up a TCP listener, which is impossible in a browser/WASM environment (no raw sockets). To save ~2.7MB, the WASM build stubs out Serve() to always return this error. There is no way to enable serving from the browser bundle.

Source

Thrown at pkg/api/serve_wasm.go:11

//go:build js && wasm
// +build js,wasm

package api

import "fmt"

// Remove the serve API in the WebAssembly build. This removes 2.7mb of stuff.

func (*internalContext) Serve(ServeOptions) (ServeResult, error) {
	return ServeResult{}, fmt.Errorf("The \"serve\" API is not supported when using WebAssembly")
}

type apiHandler struct {
}

func (*apiHandler) broadcastBuildResult(BuildResult, map[string]string) {
}

func (*apiHandler) stop() {
}

View on GitHub (pinned to 6ff1d8b0d8)

Solutions

1. Use the native (non-WASM) esbuild package if you need the serve API.
2. Feature-detect: do not call Serve() when running under WASM.
3. Run your own HTTP server in Node/host and use esbuild-wasm only for bundling.
4. Branch your code: serve with native esbuild, build-only with wasm.

Example fix

// before (browser)
import * as esbuild from 'esbuild-wasm';
await esbuild.context(opts).Serve({ port: 8000 }); // not supported

// after
import * as esbuild from 'esbuild'; // native build
await esbuild.context(opts).Serve({ port: 8000 });

const isWasm = typeof WebAssembly !== 'undefined' && /wasm/i.test(esbuild.version || '');
if (isWasm) throw new Error('serve API unsupported in WASM; use native esbuild');

function isWasmServeUnsupportedError(e) { return /serve.*not supported.*WebAssembly/.test(e?.message || ''); }

try { await ctx.Serve(opts); } catch (e) { if (isWasmServeUnsupportedError(e)) { /* switch to native esbuild or skip serving */ } throw e; }

When it happens

Trigger: Importing esbuild's WASM package (esbuild-wasm) and calling context.Serve(...) or the serve API. The WASM-only Serve override at serve_wasm.go:11 unconditionally returns the error.

Common situations: Using esbuild-wasm in the browser and attempting to start a dev server; code written against the native esbuild that is later pointed at the wasm build; a feature-detection gap where serve is called without checking the runtime.

Related errors

• Must provide either the "wasmURL" option or the "wasmModule"
• The "write" option is unavailable in this environment
• Cannot use the "serve" API in this environment
• Failed to download ${JSON.stringify(wasm)}
• Cannot serve a disposed context

AI-assisted analysis of evanw/esbuild@6ff1d8b0d8 (2026-08-03). Data as JSON: /data/errors/410705585aa98802.json. Report an issue: GitHub.