transponder is a Go proxy I've been building. It has a --config-test flag: load the config, validate it, exit 0 or 1. It runs in CI and in the deploy script before anything starts.

Last week a config passed --config-test and the server died 200 ms later with:

listen tcp: lookup tcp/nope: unknown port 

No key name, no line number, nothing to grep for. The config had listen_addr: ":nope".

The check I wrote

Validation did the obvious thing: net.SplitHostPort, then strconv.Atoi and a range check. It felt correct because the standard library was doing the parsing.

SplitHostPort is a splitter, not a validator. Here it is against the values that kill net.Listen (Go 1.27.1, on this box):

SplitHostPort(":") = "", "", <nil> SplitHostPort(":nope") = "", "nope", <nil> SplitHostPort(":70000") = "", "70000", <nil> SplitHostPort("localhost:+80") = "localhost", "+80", <nil> 

Every one splits fine. net.Listen disagrees with some of them:

:nope -> listen tcp: lookup tcp/nope: unknown port :70000 -> listen tcp: address 70000: invalid port : -> ok on [::]:39331 :+0 -> ok on [::]:44017 

: — the value that looks most broken — binds a free port quite happily. And :+0 binds too: signed ports are legal, which I had assumed they weren't. So the port has to be read the way net.Listen reads it — a number in 0–65535, or a service name resolved through net.LookupPort — and not with whatever cut the string.

func splitListenAddr(key, addr string) (host string, port int, err error) { rawHost, rawPort, err := net.SplitHostPort(addr) if err != nil || rawPort == "" { return "", 0, fmt.Errorf("config: %s %q must be host:port, such as :8080", key, addr) } if n, err := strconv.Atoi(rawPort); err == nil { if n < 0 || n > 65535 { return "", 0, fmt.Errorf("config: %s %q has the port %q, which must be between 0 and 65535", key, addr, rawPort) } return rawHost, n, nil } n, err := net.LookupPort("tcp", rawPort) if err != nil { return "", 0, fmt.Errorf("config: %s %q names the port %q, which is neither a number nor a known service", key, addr, rawPort) } return rawHost, n, nil } 

No socket opened, no DNS. LookupPort reads the local service list, which is the same list net.Listen would read.

Then the two-listener case

The service has a main listener and an ops listener. The same port on both is a startup failure, so the config check compares them — except when either port is 0, which asks the kernel for a free one.

Comparing hosts is net.IP.Equal plus case folding, with a zone split off first because net.ParseIP doesn't read zones. Fine. Then I wrote the wildcard rule: an unspecified address reaches everything, so refuse it next to any host on the same port.

CodeRabbit said I had that backwards for 0.0.0.0 next to [::1]. I said no — they bind separately, the v4 wildcard is v4.

They were right, and it took one command:

$ go run . # listen on 0.0.0.0:42771, then [::1]:42771 [::1]:42771 -> listen tcp [::1]:42771: bind: address already in use 

Go's favoriteAddrFamily opens an IPv4 wildcard as a dual-stack AF_INET6 socket, so 0.0.0.0 claims the v6 side as well. ss -lnt6 lists it, ss -lnt4 doesn't. My mental model came from C, not from net/ipsock_posix.go.

What shipped is the conservative rule: any unspecified host conflicts with anything on that port. On a platform that binds the v4 wildcard v4-only, that refuses a pair which would have worked — and a config that passes and then can't start is exactly the bug the check exists to catch.

Zones are the same story

net.ParseIP ignores zones, so fe80::1%eth0 and fe80::1%eth1 compare equal and a real collision between two interfaces slips through. Split on the first %, compare address and zone separately, and refuse what net.Listen refuses:

127.0.0.1%lo:0 -> lookup 127.0.0.1%lo: no such host (v4 takes no zone) [fe80::1%]:0 -> lookup fe80::1%: no such host (empty zone) [fe80::1%eth0%x]:0 -> bind: invalid argument (second %) 

The rule

A config check earns its keep only if it reads each value the way the consumer reads it. Same parser, same edge cases, same refusals — or explicit, documented strictness where reproducing the consumer is impossible. Anything else is a linter wearing a --config-test sticker: it approves the file, the process dies anyway, and the error arrives without the key that caused it.

Eighty lines and two test tables to move one class of startup failure from 11pm to CI. Worth it. The patch is #206 on raven-clown/transponder if you want to read the reject cases.