gohugoio/hugo · error

style %q does not have a %q mode

Error message

style %q does not have a %q mode

What it means

After validating the mode string, Hugo asks Chroma for the style variant via `styles.GetForMode(name, mode)` and then checks that the returned style actually is in the requested mode. Many Chroma styles ship only a single (usually light) variant, so requesting e.g. the dark variant of a light-only style falls back to a style whose `Mode()` doesn't match, and Hugo fails fast rather than silently emitting the wrong palette.

Source

Thrown at markup/highlight/chromastyles.go:72

	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)
	}
	style, err := builder.Build()
	if err != nil {
		return "", err
	}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Pick a Chroma style that has the requested mode — pairs like "github"/"github-dark" or a style with registered light+dark variants.
2. Use two explicit styles (one per mode) instead of one style with two modes, generating each stylesheet separately.
3. Drop the mode option and let the style's native mode be used.

Example fix

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

if styles.Get(styleName) == nil {
    return fmt.Errorf("unknown chroma style %q", styleName)
}
// then check the style actually declares the requested mode variant before use

When it happens

Trigger: `hugo gen chromastyles --style=<name> --mode=<light|dark>` where the named Chroma style has no variant registered for that mode — e.g. asking for the "dark" mode of a light-only style like "friendly", or "light" for a dark-only style.

Common situations: Theme authors generating paired light/dark stylesheets for the class-based (`noClasses=false`) workflow and assuming every Chroma style has both variants; upgrading Chroma/Hugo and finding a style's mode support changed; copying a dual-mode build script between styles without checking mode availability.

Related errors

• invalid style: %s
• invalid mode: %s
• style %q does not have a light or dark mode
• targetPath cannot be empty
• invalid Highlight option: %s

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