matryer/xbar · error

unknown parameter: %s

Error message

unknown parameter: %s

What it means

This error occurs when a key in the plugin item's parameter string matches none of the recognized keys (disabled, key, href, color, font, size, shell, bash, templateImage, image, terminal, refresh, dropdown, length, trim, alternate, emojize, ansi) and does not start with 'param'. setValueByKey returns 'unknown parameter: <key>'. Keys are matched case-sensitively, so 'Refresh' or 'Terminal' also fail.

Source

Thrown at pkg/plugins/item_params.go:270

		var err error
		p.ANSI, err = parseBool(value)
		if err != nil {
			return errors.Wrap(err, key)
		}
	default:
		if strings.HasPrefix(key, "param") {
			paramIndex, err := strconv.Atoi(key[5:])
			if err != nil {
				return errors.Errorf("bad parameter: %s (should be paramN)", key)
			}
			for len(p.ShellParams) < paramIndex {
				// ensure the slice is big enough
				p.ShellParams = append(p.ShellParams, "")
			}
			p.ShellParams[paramIndex-1] = value
			return nil
		}
		return errors.Errorf("unknown parameter: %s", key)
	}
	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) {

View on GitHub (pinned to d624239058)

Solutions

1. Check the key spelling against the supported list and fix it (e.g. icon -> image, templateimage -> templateImage).
2. Match exact case — keys are case-sensitive (Refresh != refresh).
3. Remove the unknown key if it has no effect, or move that data into the item content/attributes where appropriate.
4. For extra values meant for a shell command, use param1=..., param2=... instead of an arbitrary key.

Example fix

// before
params := "icon=.png-battery"
// after
params := "image=.png-battery"

var knownKeys = map[string]bool{
    "disabled": true, "key": true, "href": true, "color": true,
    "font": true, "size": true, "shell": true, "bash": true,
    "templateImage": true, "image": true, "terminal": true,
    "refresh": true, "dropdown": true, "length": true, "trim": true,
    "alternate": true, "emojize": true, "ansi": true,
}
for _, kv := range strings.Split(params, ",") {
    k := strings.SplitN(kv, "=", 2)[0]
    if !knownKeys[k] && !strings.HasPrefix(k, "param") {
        return fmt.Errorf("unknown key %q", k)
    }
}

func isKnownParamKey(k string) bool {
    return knownKeys[k] || strings.HasPrefix(k, "param")
}

if err := item.ParseParams(raw); err != nil {
    if strings.Contains(err.Error(), "unknown parameter") {
        log.Printf("typo in %q: %v", raw, err)
        raw = removeParam(raw, offendingKey(err))
    }
}

When it happens

Trigger: Parsing a param string with keys like 'option=...', 'icon=...', 'Refresh=true' (wrong case), or 'shellin=...' — any unrecognized key name.

Common situations: Authors invent keys based on guesses (icon instead of image), copy keys from other menu bar apps' metadata formats, capitalize keys, or misremember camelCase keys like templateImage as templateimage.

Related errors

• refresh
• dropdown
• length
• trim
• alternate

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