juanfont/headscale · error · ErrPortMustBePositive

first port must be >0, or use '*' for wildcard

Error message

first port must be >0, or use '*' for wildcard

What it means

ErrPortMustBePositive is returned by parsePortRange (hscontrol/policy/v2/utils.go:128) when a single (non-range) port token parses to a number less than 1 — in practice port 0. Port 0 is not a usable destination port; the wildcard (which covers 0-65535) must be written as "*" instead.

Source

Thrown at hscontrol/policy/v2/utils.go:21

import (
	"errors"
	"fmt"
	"net/netip"
	"slices"
	"strconv"
	"strings"

	"tailscale.com/tailcfg"
)

// Port parsing errors.
var (
	ErrInputMissingColon      = errors.New("input must contain a colon character separating destination and port")
	ErrInputStartsWithColon   = errors.New("input cannot start with a colon character")
	ErrInputEndsWithColon     = errors.New("input cannot end with a colon character")
	ErrInvalidPortRangeFormat = errors.New("invalid port range format")
	ErrPortRangeInverted      = errors.New("invalid port range: first port is greater than last port")
	ErrPortMustBePositive     = errors.New("first port must be >0, or use '*' for wildcard")
	ErrInvalidPortNumber      = errors.New("invalid first integer")
	ErrPortNumberOutOfRange   = errors.New("port number out of range")
	ErrBracketsNotIPv6        = errors.New("square brackets are only valid around IPv6 addresses")
)

// splitDestinationAndPort takes an input string and returns the destination and port as a tuple, or an error if the input is invalid.
// It supports two bracketed IPv6 forms:
//   - "[addr]:port" (RFC 3986, e.g. "[::1]:80")
//   - "[addr]/prefix:port" (e.g. "[fd7a::1]/128:80,443")
//
// Brackets are only accepted around IPv6 addresses, not IPv4, hostnames, or other alias types.
// Bracket stripping reduces both forms to bare "addr:port" or "addr/prefix:port",
// which the normal [strings.LastIndex] of ":" split handles correctly because
// port strings never contain colons.
func splitDestinationAndPort(input string) (string, string, error) {
	// Handle RFC 3986 bracketed IPv6 (e.g. "[::1]:80" or "[fd7a::1]/128:80,443").
	// Strip brackets after validation and fall through to normal parsing.
	if strings.HasPrefix(input, "[") {

View on GitHub (pinned to 565fd254d0)

Solutions

1. Use "*" for the wildcard: "host:*"
2. Or specify a real port >= 1
3. Fix generators/templates that emit port 0

Example fix

// before
"dst": ["tag:web:0"]
// after
"dst": ["tag:web:*"]

func portPositive(tok string) bool {
    if tok == "*" { return true }
    n, err := strconv.Atoi(tok)
    return err == nil && n >= 1
}

if errors.Is(err, policyv2.ErrPortMustBePositive) {
    // replace 0 with "*" or a port >= 1
}

When it happens

Trigger: Dst port sections like "host:0" as a single token. Raised in the non-hyphen branch of parsePortRange when parsePort succeeds but port < 1.

Common situations: Using 0 as shorthand for 'any port' (coming from other firewall syntaxes); templating a port variable that defaults to 0; off-by-one loops generating port lists starting at 0.

Related errors

• input must contain a colon character separating destination
• input cannot start with a colon character
• input cannot end with a colon character
• invalid first integer
• port number out of range

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