cilium/cilium · error

invalid fixed identity: expecting "<numeric-identity>=<ident

Error message

invalid fixed identity: expecting "<numeric-identity>=<identity-name>" got %q

What it means

The `--fixed-identity-mapping` flag accepts entries of the form `<numeric-identity>=<identity-name>`. A Validator registered in daemon_main.go splits the value on '=' and rejects anything that doesn't yield exactly two parts with this error. The library throws it at flag/option parse time to catch malformed identity mappings before the agent starts.

Source

Thrown at daemon/cmd/daemon_main.go:98

	argDebugVerbosePolicy   = "policy"
	argDebugVerboseTagged   = "tagged"

	apiTimeout   = 60 * time.Second
	daemonSubsys = "daemon"

	// fatalSleep is the duration Cilium should sleep before existing in case
	// of a log.Fatal is issued or a CLI flag is specified but does not exist.
	fatalSleep = 2 * time.Second
)

func InitGlobalFlags(logger *slog.Logger, cmd *cobra.Command, vp *viper.Viper) {
	flags := cmd.Flags()

	// Validators
	option.Config.FixedIdentityMappingValidator = option.Validator(func(val string) error {
		vals := strings.Split(val, "=")
		if len(vals) != 2 {
			return fmt.Errorf(`invalid fixed identity: expecting "<numeric-identity>=<identity-name>" got %q`, val)
		}
		ni, err := identity.ParseNumericIdentity(vals[0])
		if err != nil {
			return fmt.Errorf(`invalid numeric identity %q: %w`, val, err)
		}
		if !identity.IsUserReservedIdentity(ni) {
			return fmt.Errorf(`invalid numeric identity %q: valid numeric identity is between %d and %d`,
				val, identity.UserReservedNumericIdentity.Uint32(), identity.MinimalNumericIdentity.Uint32())
		}
		lblStr := vals[1]
		lbl := labels.ParseLabel(lblStr)
		if lbl.IsReservedSource() {
			return fmt.Errorf(`invalid source %q for label: %s`, labels.LabelSourceReserved, lblStr)
		}
		return nil
	})

	option.Config.BPFMapEventBuffersValidator = option.Validator(func(val string) error {

View on GitHub (pinned to ac7b90affa)

Solutions

1. Provide the mapping in `numeric-identity=identity-name` form, e.g. `--fixed-identity-mapping=100=production-frontend`.
2. Check quoting/escaping in manifests so the '=' survives shell/Helm templating.
3. Also ensure the numeric part is valid and within the user-reserved identity range — otherwise subsequent, more specific validation errors follow.

Example fix

// before
cilium-agent --fixed-identity-mapping=100
// after
cilium-agent --fixed-identity-mapping=100=production-frontend

// validate fixed identity mapping format before passing the flag
func validFixedIdentity(v string) bool {
    parts := strings.Split(v, "=")
    return len(parts) == 2 && parts[0] != "" && parts[1] != ""
}
if !validFixedIdentity(flagValue) {
    return fmt.Errorf("mapping %q must be <numeric-identity>=<identity-name>", flagValue)
}

if err := startAgent(ctx); err != nil {
    if strings.Contains(err.Error(), "invalid fixed identity") {
        log.Printf("fix --fixed-identity-mapping to numeric-identity=identity-name format")
    }
    return err
}

When it happens

Trigger: Passing a fixed identity mapping without exactly one '=' separator, e.g. `--fixed-identity-mapping=100` or `--fixed-identity-mapping=a=b=c` (strings.Split yields != 2 parts).

Common situations: Typo'ed flag values, quoting mistakes in Helm/manifests that drop the '=' part, or users specifying an identity name without the numeric prefix.

Related errors

• not a user reserved identity
• invalid numeric identity %q: valid numeric identity is betwe
• not ready
• no cilium agent pods found
• unable to detect minimum Cilium version

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