cilium/cilium · error

unsupported IP address format

Error message

unsupported IP address format

What it means

ErrUnsupportedID indicates that an IP address string supplied to the endpoint manager could not be parsed or is in an unsupported format, so no endpoint ID can be derived from it. Lookup returns it when the given identifier is not a recognized IP/prefix form.

Source

Thrown at pkg/endpointmanager/errors.go:12

// SPDX-License-Identifier: Apache-2.0
// Copyright Authors of Cilium

package endpointmanager

import (
	"errors"
)

var (
	// ErrUnsupportedID represents an error of unsupported IP address format.
	ErrUnsupportedID = errors.New("unsupported IP address format")
)

// ErrInvalidPrefix represents the error of an invalid prefix.
type ErrInvalidPrefix struct {
	// InvalidPrefix contains the invalid prefix.
	InvalidPrefix string
}

// Error returns the string representation of the ErrInvalidPrefix.
func (e ErrInvalidPrefix) Error() string {
	return "unknown endpoint prefix '" + e.InvalidPrefix + "'"
}

// IsErrUnsupportedID returns true if the given error is the type of
// ErrUnsupportedID.
func IsErrUnsupportedID(err error) bool {
	return errors.Is(err, ErrUnsupportedID)
}

View on GitHub (pinned to ac7b90affa)

Solutions

1. Validate the IP with net.ParseIP (or netip.ParseAddr) before calling Lookup.
2. Normalize the input (strip whitespace, handle CIDR via netip.ParsePrefix if prefixes are acceptable).
3. Use errors.Is(err, manager.ErrUnsupportedID) to distinguish format problems from 'endpoint not found' and surface a client-side validation message.
4. Ensure the correct address family is enabled in the Cilium configuration (IPv4/IPv6).

Example fix

// before
ep, err := mgr.Lookup(userInput)
if err != nil {
    return err
}
// after
if net.ParseIP(strings.TrimSpace(userInput)) == nil {
    return fmt.Errorf("%q is not a valid IP address", userInput)
}
ep, err := mgr.Lookup(userInput)
if errors.Is(err, manager.ErrUnsupportedID) {
    return fmt.Errorf("unsupported IP format %q", userInput)
}

func validIP(s string) bool {
    return net.ParseIP(strings.TrimSpace(s)) != nil
}

func isErrUnsupportedID(err error) bool {
    return errors.Is(err, manager.ErrUnsupportedID)
}

ep, err := mgr.Lookup(id)
if errors.Is(err, manager.ErrUnsupportedID) {
    return fmt.Errorf("invalid identifier %q: must be a supported IP", id)
}

When it happens

Trigger: Calling endpointmanager Lookup (or helpers checked via IsErrUnsupportedID) with a malformed IP string, an IPv6 form where only IPv4 is supported, or an address family/format outside the supported set.

Common situations: Passing hostnames instead of IPs; passing CIDR strings where bare IPs are expected; typo'd or empty IP values from external integrations.

Related errors

• invalid endpoint %q, must be IP:PORT: %w
• invalid port %q: %w
• port mismatch (%d != %d), all endpoints must use the same po
• invalid IP address format: %w
• invalid multicast IP: %s

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