juanfont/headscale · error

host not defined in policy

Error message

host not defined in policy

What it means

Returned by Policy.validate (hscontrol/policy/v2/types.go:2343, 2380 for ACLs; 2582, 2620 for tests) when a host alias is referenced in an ACL src/dst or a test entry but is not defined in the policy's "hosts" map. Hosts are the only way to use a symbolic name in rules; an undefined name fails the whole policy.

Source

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

	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")
	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
}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Add the alias to hosts: "hosts": {"myhost": "100.100.100.100"}
2. Check spelling/case of the reference — host names are case-sensitive
3. If the name was meant to be a user, add the @ ("user@example.com"); a bare word is treated as a host

Example fix

// before
"acls": [{"action": "accept", "src": ["myhost"], "dst": ["*:22"]}]
// (no hosts section)

// after
"hosts": {"myhost": "100.100.100.100"},
"acls": [{"action": "accept", "src": ["myhost"], "dst": ["*:22"]}]

// Collect all bare-word aliases and ensure each is a defined host
func validateHostRefs(hosts map[string]string, refs []string) error {
	for _, r := range refs {
		if !strings.Contains(r, "@") && !strings.Contains(r, ":") && !strings.Contains(r, "/") {
			if _, ok := hosts[r]; !ok {
				return fmt.Errorf("host %q not defined", r)
			}
		}
	}
	return nil
}

func isHostNotDefined(err error) bool {
	return errors.Is(err, policy.ErrHostNotDefined)
}

if err := p.Validate(); err != nil {
	if errors.Is(err, policy.ErrHostNotDefined) {
		// validation collects ALL errors; iterate them to fix every host at once
		return fmt.Errorf("undefined host alias(es): %w", err)
	}
	return err
}

When it happens

Trigger: Policy with "acls": [{"src": ["myhost"], ...}] where "hosts" has no "myhost" key. Same check applies to host references inside "tests" src/dst. Collected alongside all other validation errors and reported together.

Common situations: Typos or case mismatches (MyHost vs myhost), deleting a hosts entry while rules still reference it, renaming a host without updating rules. Note a bare name without @, :, or / parses as a Host alias — so a misspelled username like "userexample" (missing @) surfaces as an undefined host, which is confusing.

Related errors

• %w: %q
• 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/14fc4ea76f7314c7. Report an issue: GitHub.