cilium/cilium · error

unknown option %s

Error message

unknown option %s

What it means

OptionLibrary.Validate looks up the option name in the registered option table; if Lookup returns an empty key, the name is unknown and this error is thrown before any value validation.

Source

Thrown at pkg/option/option.go:122

	for k, v := range n {
		_, newVal, _, err := l.parseKeyValue(k, v)
		if err != nil {
			return nil, err
		}

		if err := l.Validate(k, v); err != nil {
			return nil, err
		}
		o[k] = newVal
	}

	return o, nil
}

func (l OptionLibrary) Validate(name string, value string) error {
	key, spec := l.Lookup(name)
	if key == "" {
		return fmt.Errorf("unknown option %s", name)
	}

	if spec.Immutable {
		return fmt.Errorf("specified option is immutable (read-only)")
	}

	if spec.Verify != nil {
		return spec.Verify(key, value)
	}

	return nil
}

type OptionMap map[string]OptionSetting

func (om OptionMap) DeepCopy() OptionMap {
	return maps.Clone(om)
}

View on GitHub (pinned to ac7b90affa)

Solutions

1. Check the exact option name against the registered option list (Lookup/table in pkg/option).
2. Fix typos and match case exactly.
3. If upgrading, consult the changelog for renamed or removed options and update configs accordingly.

Example fix

// before
Validate("monitor-aggreation", "5")
// after
Validate("monitor-aggregation-level", "5")

if _, ok := knownOptions[name]; !ok {
	return fmt.Errorf("option %q is not registered", name)
}

if err := lib.Validate(name, value); err != nil {
	if strings.HasPrefix(err.Error(), "unknown option") {
		return fmt.Errorf("%w; check spelling and current version's option list", err)
	}
	return err
}

When it happens

Trigger: Calling Validate (directly or via UpsertDevice/DeleteDevice flows) with an option name not present in the library, e.g. a typo like 'monitor-aggreation' or a deprecated/renamed option.

Common situations: Version upgrades where an option was renamed or removed; typos in ConfigMaps; case-sensitive name mismatches.

Related errors

• unexpected event buffer config value format, should be in fo
• could not parse event buffer enabled: must be either 'enable
• could not parse event buffer maxSize int: %w
• could not parse event buffer ttl duration: %w
• event buffer max size cannot be less than zero (%d)

AI-assisted analysis of cilium/cilium@ac7b90affa (2026-08-31). Data as JSON: /api/errors/7d3ebe37fad24931. Report an issue: GitHub.