juanfont/headscale · error · ErrPortRangeInverted

invalid port range: first port is greater than last port

Error message

invalid port range: first port is greater than last port

What it means

ErrPortRangeInverted is returned by parsePortRange (hscontrol/policy/v2/utils.go:117) when a port range's first port is numerically greater than its last. Ranges are written low-high; headscale does not auto-swap an inverted range but rejects it so the intent is never silently misread.

Source

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

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.

View on GitHub (pinned to 565fd254d0)

Solutions

1. Swap the endpoints so the smaller port comes first: "80-443"
2. If you meant a single port, write it without the range: "443"
3. Double-check any templated start/end variables for reversed binding

Example fix

// before
"dst": ["tag:web:443-80"]
// after
"dst": ["tag:web:80-443"]

func portRangeOrdered(tok string) bool {
    if !strings.Contains(tok, "-") { return true }
    parts := strings.SplitN(tok, "-", 2)
    a, e1 := strconv.Atoi(parts[0]); b, e2 := strconv.Atoi(parts[1])
    return e1 == nil && e2 == nil && a <= b
}

if errors.Is(err, policyv2.ErrPortRangeInverted) {
    // swap endpoints so the smaller port is first
}

When it happens

Trigger: Dst port sections like "host:443-80" or "host:8080-80". Raised after both endpoints parse successfully and first > last.

Common situations: Writing the well-known port second out of habit ("443-80"); swapping variables in a template; quick manual edits of range endpoints.

Related errors

• invalid port range format
• input must contain a colon character separating destination
• input cannot start with a colon character
• input cannot end with a colon character
• first port must be >0, or use '*' for wildcard

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