What causes "expected hex string or named color" in matryer/xbar?

Provide a valid color value after the parameter, e.g. | color=#FF0000 or | color=red

expected hex string or named color

Error message

expected hex string or named color

What it means

parseColor validates a plugin-provided color value (named color, #RGB, #RGBA, #RRGGBB or #RRGGBBAA). This error is thrown when the color value is an empty string, i.e. no color was supplied at all. The library needs a non-empty token before it can decide whether it is a hex literal or a named color.

Source

Thrown at pkg/plugins/item_params.go:290

	return nil
}

// parseBool parses a boolean from a string (either `true` or `false`),
// returning a nice error if it fails.
func parseBool(s string) (bool, error) {
	b, err := strconv.ParseBool(s)
	if err != nil {
		return false, errors.Errorf(`expected "true" or "false", not "%s"`, s)
	}
	return b, nil
}

// parseColor parses the color value given.
// Valid values: named color, #RGB, #RGBA, #RRGGBB, #RRGGBBAA.
// Returns a nice error if it fails.
func parseColor(s string) (string, error) {
	if len(s) == 0 {
		return "", errors.Errorf("expected hex string or named color") // Probably an error?
	}
	s = strings.ToLower(s)
	if s[0] == '#' {
		// Matches #RGB #RGBA #RRGGBB #RRGGBBAA
		if !colorRegexp.Match([]byte(s)) {
			return "", errors.Errorf(`invalid hex format "%s"`, s)
		}
		return s, nil
	}
	hexValue, valid := namedColors[s]
	if !valid {
		return "", errors.Errorf(`invalid named color "%s"`, s)
	}
	return hexValue, nil
}

// parseInt parses an int from a string, returning a nice
// error if it fails.

View on GitHub (pinned to d624239058)

Solutions

Provide a valid color value after the parameter, e.g. | color=#FF0000 or | color=red
In the plugin script, guard against unset variables: use ${COLOR:-#FFFFFF} or skip emitting the parameter when empty
Remove the empty color= parameter entirely if you don't need a custom color

Example fix

// before
echo "Item | color=$COLOR"   # COLOR unset -> color=
// after
echo "Item | color=${COLOR:-#FF0000}"

Defensive patterns

Strategy: validation

Validate before calling

if color == "" {
    color = "#FFFFFF" // default before passing to the parameter pipeline
}

Prevention

Never emit a bare 'color=' parameter with no value
Default unset shell variables: ${COLOR:-#FFFFFF}
Omit the parameter entirely when no color is desired

When it happens

Trigger: setValueByKey passes an empty string to parseColor — e.g. a plugin script emits a menu parameter like | color= with nothing after the '=', or the value is stripped to empty by upstream trimming.

Common situations: Plugin authors omitting the value after 'color=' in menu output; shell variables that expand to empty ($COLOR unset) in the plugin script; accidental trailing 'color=' in the template.

Related errors

AI-assisted analysis of matryer/xbar@d624239058 (2026-09-02). Data as JSON: /api/errors/c2d080fa451d964e. Report an issue: GitHub.