evanw/esbuild · critical
Invalid source map
Error message
Invalid source map
What it means
validateSourceMap (pkg/api/api_impl.go:149) panics when BuildOptions.Sourcemap is not SourceMapNone(0), SourceMapInline(1), SourceMapLinked(2), SourceMapExternal(3), or SourceMapInlineAndExternal(4). The function returns the internal config.SourceMap mode used by the linker; an unknown enum means esbuild cannot decide how (or whether) to emit .map data, so it aborts. Reached via validateBuildOptions at options construction.
Solutions
- Set Sourcemap using api.SourceMapNone / SourceMapInline / SourceMapLinked / SourceMapExternal / SourceMapInlineAndExternal only.
- If loading config from JSON, map a string key (e.g. "linked") to the constant instead of decoding a raw number.
- Bounds-check any int-to-SourceMap cast against 0..4.
- Realign wrapper and core esbuild versions; re-vendor go.mod to a single commit.
Example fix
// before
opts := api.BuildOptions{Sourcemap: api.SourceMap(8)}
// after
opts := api.BuildOptions{Sourcemap: api.SourceMapLinked} Defensive patterns
Strategy: validation
Validate before calling
func checkSourceMap(s api.SourceMap) error {
switch s {
case api.SourceMapNone, api.SourceMapInline, api.SourceMapLinked,
api.SourceMapExternal, api.SourceMapInlineAndExternal:
return nil
}
return fmt.Errorf("invalid source map %d (want 0..4)", uint8(s))
} Type guard
func isValidSourceMap(s api.SourceMap) bool {
switch s {
case api.SourceMapNone, api.SourceMapInline, api.SourceMapLinked,
api.SourceMapExternal, api.SourceMapInlineAndExternal:
return true
}
return false
} Prevention
- Default to SourceMapNone unless you actually need maps.
- Avoid decoding JSON numbers directly into SourceMap; map from strings.
- Keep wrapper and core esbuild versions aligned.
- Add a regression test that fails if any SourceMap constant is removed/renamed upstream.
When it happens
Trigger: Assigning Sourcemap from an out-of-range integer or a deserialized struct where the field is `uint8`. Common when config is shipped over a wire format (JSON, msgpack) and later cast to SourceMap without bounds checking.
Common situations: Persisted build configs that predate a renamed enum, version drift between a wrapper (e.g. Vite/webpack-loader internals) and the vendored esbuild, or a typo such as `Sourcemap: api.SourceMapBoth` (no such constant).
Related errors
AI-assisted analysis of evanw/esbuild@f6058f8364 (2026-08-09).
Data as JSON: /api/errors/65cd442765235bdf.
Report an issue: GitHub.
Appendix: source
Thrown at pkg/api/api_impl.go:149
default:
panic("Invalid format")
}
}
func validateSourceMap(value SourceMap) config.SourceMap {
switch value {
case SourceMapNone:
return config.SourceMapNone
case SourceMapLinked:
return config.SourceMapLinkedWithComment
case SourceMapInline:
return config.SourceMapInline
case SourceMapExternal:
return config.SourceMapExternalWithoutComment
case SourceMapInlineAndExternal:
return config.SourceMapInlineAndExternal
default:
panic("Invalid source map")
}
}
func validateLegalComments(value LegalComments, bundle bool) config.LegalComments {
switch value {
case LegalCommentsDefault:
if bundle {
return config.LegalCommentsEndOfFile
} else {
return config.LegalCommentsInline
}
case LegalCommentsNone:
return config.LegalCommentsNone
case LegalCommentsInline:
return config.LegalCommentsInline
case LegalCommentsEndOfFile:
return config.LegalCommentsEndOfFile
case LegalCommentsLinked:View on GitHub (pinned to f6058f8364)