evanw/esbuild · critical

Invalid legal comments

Error message

Invalid legal comments

What it means

validateLegalComments (pkg/api/api_impl.go:172) panics when BuildOptions.LegalComments is outside the enum LegalCommentsDefault(0), LegalCommentsNone(1), LegalCommentsInline(2), LegalCommentsEndOfFile(3), LegalCommentsLinked(4), LegalCommentsExternal(5). The Default branch is resolved using the `bundle` flag (end-of-file when bundling, inline otherwise); any other numeric value has no defined behavior and aborts.

Solutions

1. Use api.LegalCommentsDefault (recommended — adapts to bundle mode) or one of None/Inline/EndOfFile/Linked/External.
2. Validate decoded integers against 0..5 before casting to LegalComments.
3. Prefer the zero value (LegalCommentsDefault) when in doubt rather than guessing a number.
4. Rebuild generated/bridge code after re-vendoring esbuild.

Example fix

// before
opts := api.BuildOptions{LegalComments: api.LegalComments(12), Bundle: true}

// after
opts := api.BuildOptions{LegalComments: api.LegalCommentsDefault, Bundle: true}

func checkLegalComments(lc api.LegalComments) error {
    switch lc {
    case api.LegalCommentsDefault, api.LegalCommentsNone, api.LegalCommentsInline,
        api.LegalCommentsEndOfFile, api.LegalCommentsLinked, api.LegalCommentsExternal:
        return nil
    }
    return fmt.Errorf("invalid legal comments %d (want 0..5)", uint8(lc))
}

func isValidLegalComments(lc api.LegalComments) bool {
    switch lc {
    case api.LegalCommentsDefault, api.LegalCommentsNone, api.LegalCommentsInline,
        api.LegalCommentsEndOfFile, api.LegalCommentsLinked, api.LegalCommentsExternal:
        return true
    }
    return false
}

When it happens

Trigger: Passing a raw/cast integer for LegalComments, or a deserialized value. Called from validateBuildOptions, so the panic surfaces from api.Build/Context/Transform.

Common situations: Config migration scripts that write the field as a number, broken bridges after an esbuild upgrade that added a new enum variant, or code that hand-crafted a BuildOptions literal with an invented constant name.

Related errors

• Invalid charset
• Invalid color
• Invalid engine name
• Invalid format
• Invalid loader

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

Appendix: source

Thrown at pkg/api/api_impl.go:172

	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:
		return config.LegalCommentsLinkedWithComment
	case LegalCommentsExternal:
		return config.LegalCommentsExternalWithoutComment
	default:
		panic("Invalid legal comments")
	}
}

func validateColor(value StderrColor) logger.UseColor {
	switch value {
	case ColorIfTerminal:
		return logger.ColorIfTerminal
	case ColorNever:
		return logger.ColorNever
	case ColorAlways:
		return logger.ColorAlways
	default:
		panic("Invalid color")
	}
}

func validateLogLevel(value LogLevel) logger.LogLevel {
	switch value {

View on GitHub (pinned to f6058f8364)