cilium/cilium · error

interface name contains invalid characters: %q (allowed: a-z

Error message

interface name contains invalid characters: %q (allowed: a-z A-Z 0-9 . _ -)

What it means

ValidateInterfaceName checks names against validIfNameRegex, which permits only letters, digits, dots, underscores, and hyphens. This error means the requested interface name contains characters the kernel or the library disallows (e.g. '/', ':', spaces, '@').

Source

Thrown at pkg/networkdriver/types/types.go:86

)

// ValidateInterfaceName validates an interface name according to Linux rules
func ValidateInterfaceName(name string) error {
	// Empty name is valid (means no custom rename)
	if name == "" {
		return nil
	}

	// Check length limit (Linux IFNAMSIZ - 1)
	if len(name) > MaxInterfaceNameLength {
		return fmt.Errorf(
			"interface name too long: %q (%d chars, max %d)",
			name, len(name), MaxInterfaceNameLength)
	}

	// Check for valid characters
	if !validIfNameRegex.MatchString(name) {
		return fmt.Errorf(
			"interface name contains invalid characters: %q (allowed: a-z A-Z 0-9 . _ -)",
			name)
	}

	// Check for reserved names
	if name == "lo" {
		return fmt.Errorf("interface name %q is reserved (loopback)", name)
	}

	if len(name) >= 7 && name[:7] == "cilium_" {
		return fmt.Errorf("interface name %q is reserved (cilium_ prefix)", name)
	}

	return nil
}

type DeviceManagerType int

View on GitHub (pinned to ac7b90affa)

Solutions

1. Sanitize the interface name: replace invalid characters with '-' or '_' before calling.
2. Trim whitespace from configuration values that supply the name.
3. Validate generated names with a regex like ^[a-zA-Z0-9._-]+$ in your own generator.

Example fix

// before
name := "eth0:alias" // ':' invalid
// after
name := "eth0-alias"
if !regexp.MustCompile(`^[a-zA-Z0-9._-]+$`).MatchString(name) { /* sanitize */ }

var validIfName = regexp.MustCompile(`^[a-zA-Z0-9._-]+$`)
name = strings.TrimSpace(name)
if !validIfName.MatchString(name) {
    name = validIfName.ReplaceAllString(name, "_") // or reject
}

func isValidIfName(name string) bool {
    return regexp.MustCompile(`^[a-zA-Z0-9._-]+$`).MatchString(name)
}

if err := types.ValidateInterfaceName(name); err != nil {
    if strings.Contains(err.Error(), "invalid characters") {
        name = sanitize(name)
        return types.ValidateInterfaceName(name)
    }
    return err
}

When it happens

Trigger: Calling ValidateInterfaceName (via any name-accepting API) with a name containing characters outside [a-zA-Z0-9._-], such as 'eth 0', 'eth:0', or a name with a slash.

Common situations: Using VLAN-style 'eth0.100' style with extra separators like ':' for aliases; accidental whitespace from untrimmed config values; templated names interpolating un-sanitized identifiers.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• interface name too long: %q (%d chars, max %d)
• interface name %q is reserved (loopback)
• interface name %q is reserved (cilium_ prefix)
• failed to parse peer address %q: %w
• netkit validation failed: %w

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