juanfont/headscale · error · ErrTagNameMustStartWithLetter

tagOwners[%q]: %w

Error message

tagOwners[%q]: %w

What it means

Error "tagOwners[%q]: %w" thrown in juanfont/headscale.

Source

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

				ptr := serr.JSONPointer
				name := ptr.LastToken()

				return nil, fmt.Errorf("%w: %q", ErrUnknownField, name)
			}

			// Non-tag entries in grant.via surface as type errors on
			// []Tag; rephrase to the wire-compatible body.
			if strings.Contains(string(serr.JSONPointer), "/via/") {
				return nil, ErrGrantViaNotATag
			}

			// Non-ASCII tag-name failures surface from Tag.Validate
			// at unmarshal time. Reshape to `tagOwners["tag:X"]: …`.
			if errors.Is(serr.Err, ErrTagNameMustStartWithLetter) {
				ptr := serr.JSONPointer
				name := ptr.LastToken()

				return nil, fmt.Errorf("tagOwners[%q]: %w", name, ErrTagNameMustStartWithLetter)
			}
		}

		return nil, fmt.Errorf("parsing policy from bytes: %w", err)
	}

	if err := policy.validate(); err != nil { //nolint:noinlineerr
		return nil, err
	}

	return &policy, nil
}

// validateProtocolPortCompatibility checks that only TCP, UDP, and SCTP [Protocol]s
// can have specific ports. All other [Protocol]s should only use wildcard ports.
func validateProtocolPortCompatibility(protocol Protocol, destinations []AliasWithPorts) error {
	// Only TCP, UDP, and SCTP support specific ports
	supportsSpecificPorts := protocol == ProtocolNameTCP || protocol == ProtocolNameUDP || protocol == ProtocolNameSCTP || protocol == ""

View on GitHub (pinned to 565fd254d0)

Solutions

1. Inspect the wrapped error for the underlying cause and correct the failing condition (tagOwners[]); 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 (tagOwners[]); retry the operation after fixing the input, configuration, or environment.

When it happens

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

Common situations: A tagOwners entry for the named tag failed to parse. Ensure its value is an array of valid users or groups.

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