wavetermdev/waveterm · error

invalid config key

Error message

invalid config key: %s

What it means

SetBaseConfigValue rejects config keys that are not present in the known config key type registry: getConfigKeyType returns nil and the function returns 'invalid config key: %s'. Wave only accepts keys declared in its meta-constant schema.

Solutions

1. Check the exact key name against the generated settings meta constants (wconfig) or docs
2. Verify the key's domain prefix is correct (app:, term:, editor:, etc.)
3. If the key exists in a newer Wave version, upgrade the dependency/app

Example fix

// before
wconfig.SetBaseConfigValue(waveobj.MetaMapType{"term:fontsz": 14})
// after
wconfig.SetBaseConfigValue(waveobj.MetaMapType{"term:fontsize": 14})

// check against generated valid keys before setting
validKeys := wconfig.GetAllConfigKeys() // or generated map
if _, ok := validKeys[key]; !ok {
    return fmt.Errorf("unknown config key %q", key)
}

if err := wconfig.SetBaseConfigValue(m); err != nil {
    if strings.Contains(err.Error(), "invalid config key") {
        return fmt.Errorf("check key spelling/prefix against docs: %w", err)
    }
    return err
}

When it happens

Trigger: Calling SetBaseConfigValue with a MetaMapType containing a key not in the settings schema — misspelled keys, wrong prefix ('app:' vs 'term:'), or keys introduced in newer/older Wave versions.

Common situations: Typos like 'term:fontsize' vs the real key name; copying config from documentation for a different version; invented keys that were never registered.

Related errors

• invalid value type for
• cannot convert
• error reading config file
• error setting telemetry value
• socket path must be absolute

AI-assisted analysis of wavetermdev/waveterm@a4447c1563 (2026-09-01). Data as JSON: /api/errors/e012312d66b7663b. Report an issue: GitHub.

Appendix: source

Thrown at pkg/wconfig/settingsconfig.go:856

	}
	if reflect.String == ctype.Kind() {
		return num.String(), nil
	}
	return nil, fmt.Errorf("cannot convert number to %s", ctype)
}

func SetBaseConfigValue(toMerge waveobj.MetaMapType) error {
	m, cerrs := ReadWaveHomeConfigFile(SettingsFile)
	if len(cerrs) > 0 {
		return fmt.Errorf("error reading config file: %v", cerrs[0])
	}
	if m == nil {
		m = make(waveobj.MetaMapType)
	}
	for configKey, val := range toMerge {
		ctype := getConfigKeyType(configKey)
		if ctype == nil {
			return fmt.Errorf("invalid config key: %s", configKey)
		}
		if val == nil {
			delete(m, configKey)
		} else {
			rtype := reflect.TypeOf(val)
			if rtype == reflect.TypeOf(dummyNumber) {
				convertedVal, err := convertJsonNumber(val.(json.Number), ctype)
				if err != nil {
					return fmt.Errorf("cannot convert %s: %v", configKey, err)
				}
				val = convertedVal
				rtype = reflect.TypeOf(val)
			}
			if rtype != ctype {
				if ctype == reflect.PointerTo(rtype) {
					m[configKey] = &val
				} else {
					return fmt.Errorf("invalid value type for %s: %T", configKey, val)

View on GitHub (pinned to a4447c1563)