juanfont/headscale · error · ErrTestDestinationCIDR

test destination must be a single host, not a CIDR range

Error message

test destination must be a single host, not a CIDR range

What it means

ErrTestDestinationCIDR is returned by validateTestDestination (hscontrol/policy/v2/types.go:3258-3267) when a tests destination names a CIDR range rather than one specific host. Both raw /N syntax on the dst string and a hosts:-table alias whose RHS prefix is wider than a single address (Bits < Addr().BitLen) are rejected; bare IP literals (implicit /32 or /128) are fine.

Source

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

	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) {
	ips, err := ipb.IPSet()
	if err != nil {
		return resolved{}, err
	}

	return resolved{ips: *ips}, nil

View on GitHub (pinned to 565fd254d0)

Solutions

1. Point the test dst at one concrete host IP, e.g. "10.1.2.3:80"
2. Or define/point at a hosts alias whose value is a single address (full-length prefix)
3. Keep subnet-wide assertions in grants; test a representative single host instead

Example fix

// before
"hosts": {"servers": "10.1.0.0/16"}
"tests": [{"src": "user1", "accept": ["servers:80"]}]
// after
"hosts": {"web1": "10.1.0.5"}
"tests": [{"src": "user1", "accept": ["web1:80"]}]

// Verify a hosts alias is a single address before using it in tests
func hostIsSingleAddress(prefix netip.Prefix) bool {
    return prefix.Bits() == prefix.Addr().BitLen()
}

if errors.Is(err, policyv2.ErrTestDestinationCIDR) {
    // replace the CIDR/host alias dst with one concrete host IP
}

When it happens

Trigger: Test dst like "10.0.0.0/8:80" (raw slash in input), or a hosts entry "servers = 10.1.0.0/16" used as "servers:80" in a test — prefix.Bits() < Addr().BitLen() triggers the error.

Common situations: Using a subnet alias defined in hosts for convenience in tests; migrating integration assertions into tests blocks and keeping subnet destinations; assuming tests behave like ACL dsts where CIDRs are valid.

Related errors

• invalid prefix
• host not defined in policy
• test entry must have at least one of "accept" or "deny"
• test protocol must be tcp, udp, sctp, or empty
• test destination port must be a single port

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