What causes "port can not be 0" in ipfs/kubo?

Specify an explicit nonzero port, e.g. `/ip4/127.0.0.1/tcp/8080`.

port can not be 0

Error message

port can not be 0

What it means

checkPort parses the port string extracted from a p2p multiaddr and rejects port 0. Port 0 is not a usable endpoint for a p2p forward/listen (it would mean an OS-assigned ephemeral port the peer cannot target), so the command errors out.

Source

Thrown at core/commands/p2p.go:412

		sport, _ = target.ValueForProtocol(ma.P_UDP)
		if sport != "" {
			return sport, nil
		}
		return "", errors.New("address does not contain tcp or udp protocol")
	}

	sport, err := getPort()
	if err != nil {
		return err
	}

	port, err := strconv.Atoi(sport)
	if err != nil {
		return err
	}

	if port == 0 {
		return errors.New("port can not be 0")
	}

	return nil
}

// forwardLocal forwards local connections to a libp2p service
func forwardLocal(ctx context.Context, p *p2p.P2P, ps pstore.Peerstore, proto protocol.ID, bindAddr ma.Multiaddr, addr *peer.AddrInfo) (p2p.Listener, error) {
	ps.AddAddrs(addr.ID, addr.Addrs, pstore.TempAddrTTL)
	return p.ForwardLocal(ctx, addr.ID, proto, bindAddr)
}

const (
	p2pHeadersOptionName = "headers"
)

var p2pLsCmd = &cmds.Command{
	Status: cmds.Experimental,
	Helptext: cmds.HelpText{

View on GitHub (pinned to 329838acdf)

Solutions

Specify an explicit nonzero port, e.g. `/ip4/127.0.0.1/tcp/8080`.
Fix templates/scripts so the port variable is never empty or 0 when the command runs.
Pick a free port explicitly (e.g. via a port-picking step in your tooling) rather than relying on OS auto-assignment.

Example fix

// before
ipfs p2p forward /p2p/x/1.0.0 /ip4/127.0.0.1/tcp/0 <target>
// after
ipfs p2p forward /p2p/x/1.0.0 /ip4/127.0.0.1/tcp/8080 <target>

Defensive patterns

Strategy: validation

Validate before calling

sport, _ := m.ValueForProtocol(multiaddr.P_TCP)
port, err := strconv.Atoi(sport)
if err != nil || port <= 0 || port > 65535 {
    return fmt.Errorf("invalid port %q", sport)
}

Prevention

Reject port 0 in any config or template that feeds p2p commands.
Pick concrete free ports during deployment rather than relying on ephemeral assignment.
Range-check ports (1-65535) wherever multiaddrs are generated.

When it happens

Trigger: Running an `ipfs p2p` command with a listen or target multiaddr containing `/tcp/0` or `/udp/0`, e.g. `ipfs p2p listen /p2p/x /ip4/127.0.0.1/tcp/0`.

Common situations: Copy-pasting placeholder configs with port 0; templating errors where a port variable was empty and defaulted to 0; confusing port 0 (auto-assign, valid for plain TCP servers) with what p2p tunneling allows.

Related errors

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/cfb72494d2fdc022. Report an issue: GitHub.