What causes "invalid mode: %s" in gohugoio/hugo?

Set the mode to exactly "light" or "dark" (lowercase).

invalid mode: %s

Error message

invalid mode: %s

What it means

Returned by `ChromaStylesCSS` in Hugo when generating a Chroma syntax-highlighting stylesheet with an explicit `Mode` option that is neither "light" nor "dark". The function maps the mode string to a `chroma.Mode` constant and rejects anything else before looking up the style variant.

Source

Thrown at markup/highlight/chromastyles.go:67

}

// ChromaStylesCSS generates a CSS stylesheet for the Chroma code highlighter.
// This stylesheet is needed if markup.highlight.noClasses is disabled in config.
func ChromaStylesCSS(opts ChromaStylesOptions) (string, error) {
	name := strings.ToLower(opts.Style)
	if !slices.Contains(styles.Names(), name) {
		return "", fmt.Errorf("invalid style: %s", name)
	}
	var chromaStyle *chroma.Style
	if opts.Mode != "" {
		var mode chroma.Mode
		switch opts.Mode {
		case "light":
			mode = chroma.Light
		case "dark":
			mode = chroma.Dark
		default:
			return "", fmt.Errorf("invalid mode: %s", opts.Mode)
		}

		chromaStyle = styles.GetForMode(name, mode)
		if chromaStyle.Mode() != mode {
			return "", fmt.Errorf("style %q does not have a %q mode", name, opts.Mode)
		}
	} else {
		chromaStyle = styles.Get(name)
	}
	builder := chromaStyle.Builder()
	if opts.HighlightStyle != "" {
		builder.Add(chroma.LineHighlight, opts.HighlightStyle)
	}
	if opts.LineNumbersInlineStyle != "" {
		builder.Add(chroma.LineNumbers, opts.LineNumbersInlineStyle)
	}
	if opts.LineNumbersTableStyle != "" {
		builder.Add(chroma.LineNumbersTable, opts.LineNumbersTableStyle)

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Set the mode to exactly "light" or "dark" (lowercase).
If you don't need mode-specific output, omit the mode option entirely so the style's default variant is used.
Check the shell/CI variable feeding the flag isn't empty-quoted or misspelled.

Example fix

# before
hugo gen chromastyles --style=github --mode=Dark
# after
hugo gen chromastyles --style=github --mode=dark

Defensive patterns

Strategy: validation

Validate before calling

validModes := map[string]bool{"light": true, "dark": true}
if !validModes[mode] {
    return fmt.Errorf("unsupported chroma style mode %q", mode)
}

Prevention

Restrict mode input to a known enum (light/dark) before calling chroma style generation
Normalize user input with strings.ToLower and trim whitespace first
Surface allowed values in your CLI/config docs so users don't guess

When it happens

Trigger: Calling `hugo gen chromastyles` (or the internal `transform.ToCSS`/chromastyles path) with a mode flag/option set to something other than the literal strings "light" or "dark", e.g. `--mode Dark`, `--mode auto`, or a typo like "drak". An empty mode is fine; only a non-empty, non-light/dark value fails.

Common situations: Users of Hugo's newer light/dark dual-stylesheet workflow passing capitalized values ("Light", "DARK") since the switch is case-sensitive, scripting `hugo gen chromastyles` from a theme build pipeline with an interpolated variable that resolves to an unexpected value, or guessing values like "auto"/"both" from other tools' conventions.

Related errors

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/f41181f2cabb2c31.json. Report an issue: GitHub ↗.