evanw/esbuild · critical

Invalid platform

Error message

Invalid platform

What it means

A panic raised by validatePlatform when the Platform value passed to Build/Context/Transform is not one of the known enum constants (PlatformDefault, PlatformBrowser, PlatformNode, PlatformNeutral). This is an internal invariant: the public API types are supposed to make an invalid value impossible, so a panic signals either Go-API misuse (constructing an invalid Platform) or memory corruption.

Source

Thrown at pkg/api/api_impl.go:117

		parts = append(parts, config.PathTemplate{
			Data:        template,
			Placeholder: config.NoPlaceholder,
		})
	}

	return parts
}

func validatePlatform(value Platform) config.Platform {
	switch value {
	case PlatformDefault, PlatformBrowser:
		return config.PlatformBrowser
	case PlatformNode:
		return config.PlatformNode
	case PlatformNeutral:
		return config.PlatformNeutral
	default:
		panic("Invalid platform")
	}
}

func validateFormat(value Format) config.Format {
	switch value {
	case FormatDefault:
		return config.FormatPreserve
	case FormatIIFE:
		return config.FormatIIFE
	case FormatCommonJS:
		return config.FormatCommonJS
	case FormatESModule:
		return config.FormatESModule
	default:
		panic("Invalid format")
	}
}

View on GitHub (pinned to 6ff1d8b0d8)

Solutions

1. Only use the documented Platform constants; never construct Platform from an arbitrary integer.
2. If decoding from external data, validate the value is one of the known constants before assigning it to options.
3. Pin to esbuild's released API surface and avoid unsafe casts over the Platform type.
4. Add a unit test that round-trips every documented Platform value through your config loader.

Example fix

// before
opts.Platform = api.Platform(99)  // invalid cast

// after
opts.Platform = api.PlatformNode  // or Browser/Neutral/Default

// JS: nothing to validate; the typed union prevents invalid values.
// Go: guard before assigning.
func validPlatform(p api.Platform) bool {
  switch p {
  case api.PlatformDefault, api.PlatformBrowser, api.PlatformNode, api.PlatformNeutral:
    return true
  }
  return false
}

type Platform = 'browser' | 'node' | 'neutral'
function isPlatform(v: unknown): v is Platform {
  return v === 'browser' || v === 'node' || v === 'neutral'
}

When it happens

Trigger: Via the Go API, call Build with Platform set to a value cast from an out-of-range integer (e.g. Platform(99)). Not reachable from the JS API where Platform is a closed string-literal union. Fires at the start of option validation, before any file is read.

Common situations: Reflective code that decodes a Platform from JSON/protobuf into a raw int and casts without bounds-checking; cgo or unsafe code corrupting the enum; forks of esbuild that add a platform constant without updating the switch.

Related errors

• Invalid format
• Invalid source map
• Invalid legal comments
• Invalid color
• Invalid log level

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