gohugoio/hugo · error

invalid color code: %q

Error message

invalid color code: %q

What it means

hexStringToColorGo parses hex color strings used across Hugo's image processing (bgColor in imaging config, images.Filter colors, overlays, etc.). After stripping an optional leading `#`, the string must be exactly 3, 4, 6, or 8 hex digits (RGB, RGBA, RRGGBB, RRGGBBAA); any other length is rejected immediately with this error before digit validation.

Source

Thrown at resources/images/color.go:169

		return vv.ColorGo(), true, nil
	default:
		s, ok := hstrings.ToString(v)
		if !ok {
			return nil, false, nil
		}
		c, err := hexStringToColorGo(s)
		if err != nil {
			return nil, false, err
		}
		return c, true, nil
	}
}

func hexStringToColorGo(s string) (color.Color, error) {
	s = strings.TrimPrefix(s, "#")

	if len(s) != 3 && len(s) != 4 && len(s) != 6 && len(s) != 8 {
		return nil, fmt.Errorf("invalid color code: %q", s)
	}

	s = strings.ToLower(s)

	if len(s) == 3 || len(s) == 4 {
		var v strings.Builder
		for _, r := range s {
			v.WriteString(string(r) + string(r))
		}
		s = v.String()
	}

	// Standard colors.
	if s == "ffffff" {
		return color.White, nil
	}

	if s == "000000" {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Use a valid hex code of 3, 4, 6, or 8 digits, e.g. `#fff`, `#ffffff`, `#ffffffff`.
2. Replace named/functional CSS colors (`white`, `rgb(...)`) with their hex equivalents.
3. If the value comes from a template variable, guard against empty or unrendered values.

Example fix

# before (hugo.toml)
[imaging]
bgColor = "white"

# after
[imaging]
bgColor = "#ffffff"

re := regexp.MustCompile(`^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$`)
if !re.MatchString(color) { /* fix hex code */ }

When it happens

Trigger: Passing a malformed hex color like "#ff00"→ok(4) but "#ff0000f" (7 digits), "white", "rgb(255,0,0)", or an empty string to imaging `bgColor`, `images.Text`/`images.Padding` color options, or image processing spec strings like `#bgcolor`.

Common situations: Using CSS named colors or rgb() notation instead of hex; truncated/extra digits from copy-paste; template variables that render empty; double `##` prefixes (only one `#` is trimmed).

Related errors

• config needs a filename
• invalid anchor value %q in imaging config
• %q is not a valid resample filter
• language %q not found
• unsupported format: %q

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