juanfont/headscale · error

wildcard (*) is not supported as SSH destination

Error message

wildcard (*) is not supported as SSH destination

What it means

SSH unmarshaling error (hscontrol/policy/v2/types.go:2936-2939): an SSH destination alias list contains '*' (Asterix). Wildcards are not supported as SSH destinations; the error text steers you to autogroup:member (user-owned devices), autogroup:tagged (tagged devices), or explicit tags/users. Raised during policy parse, before validation proper.

Source

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

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.
const (

View on GitHub (pinned to 565fd254d0)

Solutions

1. Replace '*' with 'autogroup:member' + 'autogroup:tagged' (together they cover every node), or list explicit tags
2. Keep the src side user/group-only if you also use autogroup:self dsts (see the companion validation errors)
3. Run 'headscale policy check' after the edit

Example fix

// before
{"src": ["group:ops"], "dst": ["*"], "users": ["root"], "action": "accept"}

// after
{"src": ["group:ops"], "dst": ["autogroup:member", "autogroup:tagged"], "users": ["autogroup:nonroot"], "action": "check", "checkPeriod": "8h"}

func sshDstValid(dst []string) bool { return !slices.Contains(dst, "*") }

When it happens

Trigger: "ssh": [{"src": ["group:ops"], "dst": ["*"], "users": ["root"], "action": "accept"}] — SSHDstAliases.UnmarshalJSON hits the Asterix case and returns the wrapped error.

Common situations: Porting old policies that used '*' dsts as 'anywhere'; misunderstanding that ACL '*' semantics do not carry over to SSH; IaC templates with wildcard placeholders.

Related errors

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

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