juanfont/headscale · error

tags in SSH source cannot access autogroup:member (user-owne

Error message

tags in SSH source cannot access autogroup:member (user-owned devices)

What it means

SSH validation error (hscontrol/policy/v2/types.go:2190): an SSH rule combines a tagged src with autogroup:member in dst. autogroup:member expands to all user-owned devices, and tag-owned sources may not SSH into user-owned devices — the tagged counterpart of ErrSSHTagSourceToUserDest at the autogroup level.

Source

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

// Global JSON options for consistent parsing across all struct unmarshaling.
var policyJSONOpts = []json.Options{
	json.DefaultOptionsV2(),
	json.MatchCaseInsensitiveNames(true),
	json.RejectUnknownMembers(true),
}

const Wildcard = Asterix(0)

var ErrAutogroupSelfRequiresPerNodeResolution = errors.New("autogroup:self requires per-node resolution and cannot be resolved in this context")

var ErrUndefinedTagReference = errors.New("references undefined tag")

// SSH validation errors.
var (
	ErrSSHTagSourceToUserDest             = errors.New("tags in SSH source cannot access user-owned devices")
	ErrSSHUserDestRequiresSameUser        = errors.New("user destination requires source to contain only that same user")
	ErrSSHAutogroupSelfRequiresUserSource = errors.New("autogroup:self destination requires source to contain only users or groups, not tags or autogroup:tagged")
	ErrSSHTagSourceToAutogroupMember      = errors.New("tags in SSH source cannot access autogroup:member (user-owned devices)")
	ErrSSHWildcardDestination             = errors.New("wildcard (*) is not supported as SSH destination")
	ErrSSHCheckPeriodAboveMax             = errors.New("is above the max (168h)")
	ErrSSHCheckPeriodNegative             = errors.New("must be a positive duration")
	ErrSSHCheckPeriodOnNonCheck           = errors.New("checkPeriod is only valid with action \"check\"")
	ErrInvalidLocalpart                   = errors.New("invalid localpart format, must be localpart:*@<domain>")
	ErrSSHUsersMustBeSpecified            = errors.New("users must be specified")
	ErrSSHUserInvalid                     = errors.New("is not valid")
	ErrSSHAcceptEnvEmpty                  = errors.New("acceptEnv values cannot be empty")
	ErrSSHActionMustBeSpecified           = errors.New("action must be specified")
	ErrSSHActionInvalid                   = errors.New("is not a valid action")
	ErrSSHDestinationHostAlias            = errors.New("invalid dst")
	ErrTagNameMustStartWithLetter         = errors.New("tag names must start with a letter, after 'tag:'")
	ErrGroupMembersCannotBeRecursive      = errors.New("group members cannot be recursive")
)

// SSH check period constants per Tailscale docs:
// https://tailscale.com/docs/features/tailscale-ssh#checkperiod
// SaaS imposes no minimum (0s is accepted) so headscale matches.

View on GitHub (pinned to 565fd254d0)

Solutions

1. Switch dst to autogroup:tagged or specific tags so the rule stays tag-to-tag
2. Or drop the tag from src and use a user/group that owns the deployment targets
3. Expose automation via the network grants layer instead of SSH rules

Example fix

// before
{"src": ["tag:ci"], "dst": ["autogroup:member"], "users": ["deploy"], "action": "accept"}

// after
{"src": ["tag:ci"], "dst": ["autogroup:tagged"], "users": ["deploy"], "action": "accept"}

func sshTagSrcRuleValid(dst []string) bool { return !slices.Contains(dst, "autogroup:member") }

When it happens

Trigger: {"src": ["tag:ci"], "dst": ["autogroup:member"], "users": ["deploy"], "action": "accept"} — any tag/autogroup:tagged in src with autogroup:member in dst.

Common situations: Automation node meant to deploy everywhere; replacing a deprecated * dst with autogroup:member while keeping a tagged src; policy migration from v1-style broad SSH rules.

Related errors

• autogroup:self destination requires source to contain only u
• tags in SSH source cannot access user-owned devices
• user destination requires source to contain only that same u
• wildcard (*) is not supported as SSH destination
• is above the max (168h)

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