caddyserver/caddy · error

invalid start port: %v

Error message

invalid start port: %v

What it means

In ParseNetworkAddress, the port component (before the '-' in a range like 8080-8090, or the single port) must parse as an unsigned 16-bit integer. This error wraps the strconv failure for the start port: non-numeric text, a value > 65535, or a negative sign.

Source

Thrown at listeners.go:355

	}
	if IsFdNetwork(network) {
		return NetworkAddress{
			Network: network,
			Host:    host,
		}, nil
	}
	var start, end uint64
	if port == "" {
		start = uint64(defaultPort)
		end = uint64(defaultPort)
	} else {
		before, after, found := strings.Cut(port, "-")
		if !found {
			after = before
		}
		start, err = strconv.ParseUint(before, 10, 16)
		if err != nil {
			return NetworkAddress{}, fmt.Errorf("invalid start port: %v", err)
		}
		end, err = strconv.ParseUint(after, 10, 16)
		if err != nil {
			return NetworkAddress{}, fmt.Errorf("invalid end port: %v", err)
		}
		if end < start {
			return NetworkAddress{}, fmt.Errorf("end port must not be less than start port")
		}
		if (end - start) > maxPortSpan {
			return NetworkAddress{}, fmt.Errorf("port range exceeds %d ports", maxPortSpan)
		}
	}
	return NetworkAddress{
		Network:   network,
		Host:      host,
		StartPort: uint(start),
		EndPort:   uint(end),
	}, nil

View on GitHub (pinned to 50e54ee279)

Solutions

1. Replace service names with numbers: ':80' not ':http'.
2. Strip schemes/paths and keep only host:port or :port-range.
3. Verify both bounds are within 0-65535.

Example fix

// before
addr, err := caddy.ParseNetworkAddress(":https")
// after
addr, err := caddy.ParseNetworkAddress(":443")

var portRe = regexp.MustCompile(`^\d{1,5}$`)

func portLooksValid(p string) bool {
    if !portRe.MatchString(p) { return false }
    n, _ := strconv.Atoi(p)
    return n <= 65535
}

When it happens

Trigger: Addresses like ':http' (service names are NOT resolved), ':808O' (letter O), ':-8090', ':99999', or ':80-'. ParseUint(before, 10, 16) failing is the exact trigger.

Common situations: Using named ports ('http', 'https') which many tools accept but Caddy's parser does not; OCR/typo digits; copying URLs with schemes or paths into listen addresses.

Related errors

• invalid end port: %v
• parsing listener address: %v
• must be exactly one listener address; cannot listen on: %s
• indexing config: %v
• %s: %s field must be a string or number

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/e794584811d5a4f5. Report an issue: GitHub.