juanfont/headscale · error · ErrInvalidLocalpart

%w: missing prefix %q in %q

Error message

%w: missing prefix %q in %q

What it means

Error "%w: missing prefix %q in %q" thrown in juanfont/headscale.

Source

Thrown at hscontrol/policy/v2/types.go:3073

// IsCanonicalLocalpart reports whether the [SSHUser] parses as the
// canonical `localpart:*@<domain>` form that resolution acts on.
func (u SSHUser) IsCanonicalLocalpart() bool {
	if !u.IsLocalpart() {
		return false
	}

	_, err := u.ParseLocalpart()

	return err == nil
}

// ParseLocalpart validates and extracts the domain from a localpart: entry.
// The expected format is localpart:*@<domain>.
// Returns the domain part or an error if the format is invalid.
func (u SSHUser) ParseLocalpart() (string, error) {
	if !u.IsLocalpart() {
		return "", fmt.Errorf("%w: missing prefix %q in %q", ErrInvalidLocalpart, SSHUserLocalpartPrefix, u)
	}

	pattern := strings.TrimPrefix(string(u), SSHUserLocalpartPrefix)

	// Must be *@<domain>
	atIdx := strings.LastIndex(pattern, "@")
	if atIdx < 0 {
		return "", fmt.Errorf("%w: missing @ in %q", ErrInvalidLocalpart, u)
	}

	localPart := pattern[:atIdx]
	domain := pattern[atIdx+1:]

	if localPart != "*" {
		return "", fmt.Errorf("%w: local part must be *, got %q in %q", ErrInvalidLocalpart, localPart, u)
	}

	if domain == "" {

View on GitHub (pinned to 565fd254d0)

Solutions

1. Inspect the wrapped error for the underlying cause and correct the failing condition (); retry the operation after fixing the input, configuration, or environment.

Example fix

Inspect the wrapped error for the underlying cause and correct the failing condition (); retry the operation after fixing the input, configuration, or environment.

When it happens

Trigger: Thrown at hscontrol/policy/v2/types.go:3073 when the library encounters an invalid state.

Common situations: A policy alias string is missing its required prefix (e.g. group: or tag:). Add the proper prefix to the entry.

AI-assisted analysis of juanfont/headscale@565fd254d0 (2026-08-15). Data as JSON: /api/errors/dfe2a874a65c85fb. Report an issue: GitHub.