juanfont/headscale · error

tag must start with 'tag:'

Error message

tag must start with 'tag:'

What it means

Tag.Validate (hscontrol/policy/v2/types.go:534) requires every tag token to start with the literal prefix 'tag:'. Tags appear in tagOwners keys, grant sources/destinations, and SSH rules; without the prefix the parser cannot tell a tag from a hostname or username.

Source

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

)

// nodeAttrUnsupportedCaps lists caps that headscale parses but cannot act on
// today. Each entry maps to the tracking issue an operator can follow. The
// caps are accepted by Tailscale SaaS, but delivering them via headscale
// without the matching server-side machinery would be misleading — nodes
// would advertise a feature that does not work. Reject at policy load and
// point operators at the issue.
var nodeAttrUnsupportedCaps = map[tailcfg.NodeCapability]string{
	tailcfg.NodeAttrFunnel: "https://github.com/juanfont/headscale/issues/2527",
}

// Policy validation errors.
var (
	ErrInvalidUsername             = errors.New("username must contain @")
	ErrUserNotFound                = errors.New("user not found")
	ErrMultipleUsersFound          = errors.New("multiple users found")
	ErrInvalidGroupFormat          = errors.New("group must start with 'group:'")
	ErrInvalidTagFormat            = errors.New("tag must start with 'tag:'")
	ErrInvalidHostname             = errors.New("invalid hostname")
	ErrHostResolve                 = errors.New("error resolving host")
	ErrInvalidPrefix               = errors.New("invalid prefix")
	ErrInvalidAutogroup            = errors.New("invalid autogroup")
	ErrUnknownAutogroup            = errors.New("unknown autogroup")
	ErrHostportMissingColon        = errors.New("hostport must contain a colon")
	ErrTypeNotSupported            = errors.New("type not supported")
	ErrInvalidAlias                = errors.New("invalid alias format")
	ErrInvalidAutoApprover         = errors.New("invalid auto approver format")
	ErrInvalidOwner                = errors.New("invalid owner format")
	ErrGroupNotDefined             = errors.New("group not defined in policy")
	ErrInvalidGroupMember          = errors.New("invalid group member type")
	ErrGroupValueNotArray          = errors.New("group value must be an array of users")
	ErrInvalidHostIP               = errors.New("hostname contains invalid IP address")
	ErrTagNotDefined               = errors.New("tag not found")
	ErrAutoApproverNotAlias        = errors.New("auto approver is not an alias")
	ErrInvalidACLAction            = errors.New("invalid ACL action")
	ErrInvalidSSHAction            = errors.New("invalid SSH action")

View on GitHub (pinned to 565fd254d0)

Solutions

1. Add the 'tag:' prefix to every tag key and tag reference
2. Verify with 'headscale policy check' before applying
3. Pre-register the tag in tagOwners so nodes can claim it

Example fix

// before
{"tagOwners": {"webserver": ["group:admins"]}}
// after
{"tagOwners": {"tag:webserver": ["group:admins"]}}

for key := range policy.TagOwners {
    if !strings.HasPrefix(key, "tag:") {
        return fmt.Errorf("tag key %q must start with 'tag:'", key)
    }
}

func isTagToken(s string) bool { return strings.HasPrefix(s, "tag:") }

if errors.Is(err, policy.ErrInvalidTagFormat) {
    // add the tag: prefix to the key
}

When it happens

Trigger: Writing {"tagOwners": {"server": [...]}} instead of {"tagOwners": {"tag:server": [...]}}; using 'tagserver' or ':tag' variants. Thrown at UnmarshalJSON, so the whole policy fails to load.

Common situations: First-time policy authors copying examples that omit the prefix; mixing up group: and tag: prefixes; hand-migrating old ACLs and dropping prefixes.

Related errors

• tag not found
• test(s) failed
• nodeAttrs target does not support this autogroup
• username must contain @
• group must start with 'group:'

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