evanw/esbuild · critical

Invalid charset

Error message

Invalid charset

What it means

validateASCIIOnly (pkg/api/api_impl.go:228) panics when Charset is not CharsetDefault(0), CharsetASCII(1), or CharsetUTF8(2). The function returns a bool (ASCII-only emission) used by the linker; an unknown value has no defined escaping behavior, so esbuild aborts. Reached from validateBuildOptions.

Solutions

1. Use api.CharsetDefault (or leave unset) for ASCII-safe output, api.CharsetASCII, or api.CharsetUTF8.
2. Validate decoded integers against 0..2 before casting to Charset.
3. Serialize the setting as a string ("default"/"ascii"/"utf8") and map at load.
4. Re-vendor all consumers against a single esbuild version.

Example fix

// before
opts := api.BuildOptions{Charset: api.Charset(4)}

// after
opts := api.BuildOptions{Charset: api.CharsetUTF8}

func checkCharset(c api.Charset) error {
    switch c {
    case api.CharsetDefault, api.CharsetASCII, api.CharsetUTF8:
        return nil
    }
    return fmt.Errorf("invalid charset %d (want 0..2)", uint8(c))
}

func isValidCharset(c api.Charset) bool {
    switch c {
    case api.CharsetDefault, api.CharsetASCII, api.CharsetUTF8:
        return true
    }
    return false
}

When it happens

Trigger: Passing BuildOptions.Charset (or TransformOptions.Charset) as a raw integer or a deserialized `uint8`. Panic occurs in the option-validation pass before scanning.

Common situations: Config UIs that store charset as a small int, version drift between a wrapper and the core (e.g. a renamed CharsetASCII8 constant), or a typo like `Charset: api.CharsetLatin1` (no such constant).

Related errors

• Invalid color
• Invalid engine name
• Invalid format
• Invalid legal comments
• Invalid loader

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

Appendix: source

Thrown at pkg/api/api_impl.go:228

	case LogStyleDefault:
		return logger.StyleDefault
	case LogStyleClang:
		return logger.StyleClang
	case LogStyleVisualStudio:
		return logger.StyleVisualStudio
	default:
		panic("Invalid log style")
	}
}

func validateASCIIOnly(value Charset) bool {
	switch value {
	case CharsetDefault, CharsetASCII:
		return true
	case CharsetUTF8:
		return false
	default:
		panic("Invalid charset")
	}
}

func validateExternalPackages(value Packages) bool {
	switch value {
	case PackagesDefault, PackagesBundle:
		return false
	case PackagesExternal:
		return true
	default:
		panic("Invalid packages")
	}
}

func validateTreeShaking(value TreeShaking, bundle bool, format Format) bool {
	switch value {
	case TreeShakingDefault:
		// If we're in an IIFE then there's no way to concatenate additional code

View on GitHub (pinned to f6058f8364)