Skip to content
Go: Split host and port without breaking IPv6 addresses

Go: Split host and port without breaking IPv6 addresses

November 14, 2026

An IPv6 address contains colons, so splitting an endpoint at every colon loses its structure. net.SplitHostPort understands bracketed IPv6 host syntax. Port validation remains a separate application decision.

Set up

Tested on Linux amd64 with Go 1.26.10. Use Bash with Go on your PATH, a text editor, and the mktemp, rm, and rmdir utilities. The example uses only the standard library. Keep the same terminal through cleanup, and stop if setup fails before saving the source.

start_dir="$PWD"
work_dir="$(mktemp -d)" || exit 1
cd -- "$work_dir" || exit 1

Run the example

Save as go-net-splithostport-ipv6-boundary.go:

package main

import (
	"fmt"
	"net"
	"strconv"
)

func endpoint(text string) (string, uint16, error) {
	host, portText, err := net.SplitHostPort(text)
	if err != nil {
		return "", 0, fmt.Errorf("invalid host:port syntax")
	}
	if host == "" {
		return "", 0, fmt.Errorf("host required")
	}
	port, err := strconv.ParseUint(portText, 10, 16)
	if err != nil || port == 0 {
		return "", 0, fmt.Errorf("port must be 1..65535")
	}
	return host, uint16(port), nil
}

func main() {
	for _, text := range []string{"example.test:443", "[2001:db8::1]:443", "2001:db8::1:443", ":443", "host:0", "host:65536", "host:https"} {
		host, port, err := endpoint(text)
		fmt.Printf("%q: host=%q port=%d error=%v\n", text, host, port, err)
	}
	host, port, err := endpoint("[2001:db8::1]:443")
	if host != "2001:db8::1" || port != 443 || err != nil {
		panic("IPv6 endpoint")
	}
	fmt.Println("joined:", net.JoinHostPort(host, strconv.Itoa(int(port))))
}

Run:

go run go-net-splithostport-ipv6-boundary.go

Observed output:

"example.test:443": host="example.test" port=443 error=<nil>
"[2001:db8::1]:443": host="2001:db8::1" port=443 error=<nil>
"2001:db8::1:443": host="" port=0 error=invalid host:port syntax
":443": host="" port=0 error=host required
"host:0": host="" port=0 error=port must be 1..65535
"host:65536": host="" port=0 error=port must be 1..65535
"host:https": host="" port=0 error=port must be 1..65535
joined: [2001:db8::1]:443

Read the result

The bracketed address returns a host without brackets. JoinHostPort adds the appropriate brackets when rebuilding the endpoint. An unbracketed IPv6 literal is rejected by the split operation.

The application also rejects an empty host, port zero, named services and numbers outside the 16-bit range. Those restrictions are additional to splitting: a syntactically separated port string is not necessarily a permitted numeric port.

Apply it carefully

This function does not resolve DNS, validate the hostname or authorize a network destination. It opens no connection. A nonempty host is insufficient for security decisions such as restricting outbound requests; those require a policy covering resolution and the actual connection. The documentation address and test domain are examples only. Other applications may deliberately permit an empty bind host, named services or port zero, so keep those decisions explicit rather than attributing them to the splitter.

See the Go standard-library reference.

Clean up

Remove the saved source and the empty scratch directory. Go manages its build cache separately. If the directory is not empty, inspect its contents before removing anything else.

rm -- go-net-splithostport-ipv6-boundary.go
cd -- "$start_dir" || exit 1
rmdir -- "$work_dir"
unset start_dir work_dir

Acknowledgements

This post was created with assistance from AI.

Last updated on