juanfont/headscale · error

protocol number out of range (0-255)

Error message

protocol number out of range (0-255)

What it means

Returned by Protocol.validate (hscontrol/policy/v2/types.go:1779) when a numeric "proto" value parses as an integer but falls outside 0-255, the IANA IP protocol number range. The offending number is included in the wrapped message.

Source

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

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

View on GitHub (pinned to 565fd254d0)

Solutions

1. Use a protocol number within 0-255 (e.g. 6=tcp, 17=udp, 47=gre)
2. Double-check you did not put a port in the proto field — ports belong in dst like "tag:host:443"
3. Use a named protocol where available

Example fix

// before
{"action": "accept", "proto": "8080", "src": ["*"], "dst": ["tag:web:*"]}

// after
{"action": "accept", "proto": "tcp", "src": ["*"], "dst": ["tag:web:8080"]}

n, err := strconv.Atoi(protoStr)
if err == nil && (n < 0 || n > 255) {
	return fmt.Errorf("proto %d out of range 0-255", n)
}

func isProtocolOutOfRange(err error) bool {
	return errors.Is(err, policy.ErrProtocolOutOfRange)
}

if err := json.Unmarshal(b, &acl); err != nil {
	if errors.Is(err, policy.ErrProtocolOutOfRange) {
		return fmt.Errorf("proto number must be 0-255 (did you put a port there?): %w", err)
	}
	return err
}

When it happens

Trigger: Policy with "proto": "256", "proto": "1000", or a negative value that Atoi accepts. Anything that is not a protocol name and parses as an out-of-range integer.

Common situations: Pasting port numbers into the proto field (e.g. 8080), using an IANA service number instead of a protocol number, or generation scripts with wrong fields.

Related errors

• invalid protocol number
• leading 0 not permitted in protocol number
• protocol does not support specific ports
• proto name "*" not known; use protocol number 0-255 or proto
• test(s) failed

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