juanfont/headscale · error

alias not supported for SSH destination

Error message

alias not supported for SSH destination

What it means

Returned by SSHDstAliases.UnmarshalJSON (hscontrol/policy/v2/types.go:2941) when an element of an SSH rule's dst array decodes to a type other than *Username, *Tag, *AutoGroup, or *Host. Groups and raw IP/CIDR literals are rejected: SSH destinations are devices, identified by tag, host alias, autogroup, or (for self-SSH) a user. A "*" dst gets its own richer error (ErrSSHWildcardDestination, 2937).

Source

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

	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")
	ErrInvalidProtocolNumber       = errors.New("invalid protocol number")
	ErrProtocolLeadingZero         = errors.New("leading 0 not permitted in protocol number")
	ErrProtocolOutOfRange          = errors.New("protocol number out of range (0-255)")
	ErrAutogroupNotSupported       = errors.New("autogroup not supported in headscale")
	ErrAutogroupInternetSrc        = errors.New("autogroup:internet can only be used in ACL destinations")
	ErrAutogroupSelfSrc            = errors.New("\"autogroup:self\" not valid on the src side of a rule")
	ErrAutogroupNotSupportedACLSrc = errors.New("autogroup not supported for ACL sources")
	ErrAutogroupNotSupportedACLDst = errors.New("autogroup not supported for ACL destinations")
	ErrAutogroupDangerAllDst       = errors.New("cannot use autogroup:danger-all as a dst")
	ErrAutogroupNotSupportedSSHSrc = errors.New("autogroup not supported for SSH sources")
	ErrAutogroupNotSupportedSSHDst = errors.New("autogroup not supported for SSH destinations")
	ErrHostNotDefined              = errors.New("host not defined in policy")
	ErrSSHSourceAliasNotSupported  = errors.New("alias not supported for SSH source")
	ErrSSHDestAliasNotSupported    = errors.New("alias not supported for SSH destination")
	ErrUnknownField                = errors.New("unknown field")
	ErrProtocolNoSpecificPorts     = errors.New("protocol does not support specific ports")
	ErrTestEmptyAssertions         = errors.New("test entry must have at least one of \"accept\" or \"deny\"")
	ErrTestProtocolNotAllowed      = errors.New("test protocol must be tcp, udp, sctp, or empty")
	ErrTestDestinationMultiPort    = errors.New("test destination port must be a single port")
	ErrTestDestinationCIDR         = errors.New("test destination must be a single host, not a CIDR range")
	ErrAutogroupInternetTestDst    = errors.New("autogroup:internet not valid as a test destination")
	ErrSSHTestEmptySrc             = errors.New("SSH tests entry must have a non-empty src")
	ErrSSHTestEmptyDst             = errors.New("SSH tests entry must have at least one dst")
	ErrSSHTestDstUnknownTag        = errors.New("SSH tests dst contains unknown tag")
	ErrSSHTestDstDisallowedElement = errors.New("SSH tests dst contains disallowed element")
)

type resolved struct {
	ips netipx.IPSet
}

func newResolved(ipb *netipx.IPSetBuilder) (resolved, error) {

View on GitHub (pinned to 565fd254d0)

Solutions

1. Use a tag ("tag:server"), host alias, autogroup:member/tagged/self, or a username as SSH dst
2. Replace "*" with autogroup:member (user-owned devices) or autogroup:tagged (tagged devices)
3. Move group-based targeting to src, where groups are legal

Example fix

// before
"ssh": [{"action": "accept", "src": ["group:admin"], "dst": ["group:servers"], "users": ["root"]}]

// after
"ssh": [{"action": "accept", "src": ["group:admin"], "dst": ["tag:server"], "users": ["root"]}]

func validSSHDst(s string) bool {
	if s == "*" {
		return false // gets wildcard-specific error
	}
	return strings.HasPrefix(s, "autogroup:") || strings.HasPrefix(s, "tag:") ||
		strings.Contains(s, "@") || isDefinedHostName(s)
}

func isSSHDestAliasNotSupported(err error) bool {
	return errors.Is(err, policy.ErrSSHDestAliasNotSupported)
}

if err := json.Unmarshal(b, &p); err != nil {
	if errors.Is(err, policy.ErrSSHDestAliasNotSupported) {
		return fmt.Errorf("SSH dst must be tag/host/user/autogroup (no groups or IPs): %w", err)
	}
	return err
}

When it happens

Trigger: An SSH rule with dst containing "group:admin" (groups are user sets, not devices), or a raw address like "100.64.0.5" / "10.0.0.0/8". The rejected Go type is included in the message.

Common situations: Assuming group: works in SSH dst because it works in SSH src; pasting ACL dst lines with CIDRs into ssh rules; using "*" and expecting it to work (it produces the wildcard-specific error suggesting autogroup:member/autogroup:tagged).

Related errors

• alias not supported for SSH source
• 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/cbb31a7752d47955. Report an issue: GitHub.