juanfont/headscale · error

hostport must contain a colon

Error message

hostport must contain a colon

What it means

Hostport parsing (hscontrol/policy/v2/types.go:899) requires a host:port token to contain a colon separating host and port(s). ACL dst entries are strings like 'host:80,443'; a token with no colon cannot be split and is rejected with this sentinel at parse time.

Source

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

// would advertise a feature that does not work. Reject at policy load and
// point operators at the issue.
var nodeAttrUnsupportedCaps = map[tailcfg.NodeCapability]string{
	tailcfg.NodeAttrFunnel: "https://github.com/juanfont/headscale/issues/2527",
}

// Policy validation errors.
var (
	ErrInvalidUsername             = errors.New("username must contain @")
	ErrUserNotFound                = errors.New("user not found")
	ErrMultipleUsersFound          = errors.New("multiple users found")
	ErrInvalidGroupFormat          = errors.New("group must start with 'group:'")
	ErrInvalidTagFormat            = errors.New("tag must start with 'tag:'")
	ErrInvalidHostname             = errors.New("invalid hostname")
	ErrHostResolve                 = errors.New("error resolving host")
	ErrInvalidPrefix               = errors.New("invalid prefix")
	ErrInvalidAutogroup            = errors.New("invalid autogroup")
	ErrUnknownAutogroup            = errors.New("unknown autogroup")
	ErrHostportMissingColon        = errors.New("hostport must contain a colon")
	ErrTypeNotSupported            = errors.New("type not supported")
	ErrInvalidAlias                = errors.New("invalid alias format")
	ErrInvalidAutoApprover         = errors.New("invalid auto approver format")
	ErrInvalidOwner                = errors.New("invalid owner format")
	ErrGroupNotDefined             = errors.New("group not defined in policy")
	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")

View on GitHub (pinned to 565fd254d0)

Solutions

1. Write dst entries as 'host:ports', e.g. 'example-host:80,443'
2. Use 'host:*' to mean all ports
3. Check every dst string in the ACL/grant for the missing colon

Example fix

// before
{"acls": [{"action": "accept", "src": ["group:admins"], "dst": ["example-host"]}]}
// after
{"acls": [{"action": "accept", "src": ["group:admins"], "dst": ["example-host:*"]}]}

for _, dst := range rule.Dst {
    if dst != "*" && !strings.Contains(dst, ":") {
        return fmt.Errorf("dst %q must be host:port(s)", dst)
    }
}

func isHostport(s string) bool { return s == "*" || strings.Contains(s, ":") }

if errors.Is(err, policy.ErrHostportMissingColon) {
    // rewrite as 'host:*' or 'host:port'
}

When it happens

Trigger: Writing a dst entry as just the hostname/IP ("example-host") or just a port ("443"), forgetting the ':' separator; also 'example-host-443' with a dash instead of colon. The '*' wildcard alone is accepted; the colon-less non-wildcard is not.

Common situations: First ACL authoring: omitting ports because you meant 'all ports' (use 'host:*' instead); copy-paste from firewall rules that use space or dash separators.

Related errors

• test(s) failed
• nodeAttrs target does not support this autogroup
• username must contain @
• group must start with 'group:'
• tag must start with 'tag:'

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