What causes "serveHTTPGateway: manet.Listen(%s) failed: %s" in ipfs/kubo?

Check what holds the port: `ss -ltnp | grep 8080` (or lsof) and stop it, or pick a free port: `ipfs config Addresses.Gateway /ip4/0.0.0.0/tcp/18080`.

ipfs/kubo · error

serveHTTPGateway: manet.Listen(%s) failed: %s

Error message

serveHTTPGateway: manet.Listen(%s) failed: %s

What it means

For gateway addresses not already provided by socket activation, kubo binds the listener with manet.Listen. This error is thrown when binding fails; the message includes the multiaddr and the underlying OS/network error (address in use, permission denied, etc.).

Source

Thrown at cmd/ipfs/kubo/daemon.go:1092

	listenerAddrs := make(map[string]bool, len(listeners))
	for _, listener := range listeners {
		listenerAddrs[string(listener.Multiaddr().Bytes())] = true
	}

	gatewayAddrs := cfg.Addresses.Gateway
	for _, addr := range gatewayAddrs {
		gatewayMaddr, err := ma.NewMultiaddr(addr)
		if err != nil {
			return nil, fmt.Errorf("serveHTTPGateway: invalid gateway address: %q (err: %s)", addr, err)
		}

		if listenerAddrs[string(gatewayMaddr.Bytes())] {
			continue
		}

		gwLis, err := manet.Listen(gatewayMaddr)
		if err != nil {
			return nil, fmt.Errorf("serveHTTPGateway: manet.Listen(%s) failed: %s", gatewayMaddr, err)
		}
		listenerAddrs[string(gatewayMaddr.Bytes())] = true
		listeners = append(listeners, gwLis)
	}

	// we might have listened to /tcp/0 - let's see what we are listing on
	for _, listener := range listeners {
		fmt.Printf("Gateway server listening on %s\n", listener.Multiaddr())
	}

	if cfg.Gateway.ExposeRoutingAPI.WithDefault(config.DefaultExposeRoutingAPI) {
		for _, listener := range listeners {
			fmt.Printf("Routing V1 API exposed at http://%s/routing/v1\n", listener.Addr())
		}
	}

	cmdctx := *cctx
	cmdctx.Gateway = true

View on GitHub (pinned to 329838acdf)

Solutions

Check what holds the port: `ss -ltnp | grep 8080` (or lsof) and stop it, or pick a free port: `ipfs config Addresses.Gateway /ip4/0.0.0.0/tcp/18080`.
Kill stale daemons from previous runs: pkill -f "ipfs daemon".
For ports <1024, use IPFW/iptables redirect, setcap on the binary, or systemd socket activation instead of running as root.
Ensure the interface address exists (e.g., do not bind a specific external IP that is not assigned).

Example fix

// before: bind fails
$ ipfs config Addresses.Gateway /ip4/0.0.0.0/tcp/80
// after: unprivileged port + redirect or socket activation
$ ipfs config Addresses.Gateway /ip4/0.0.0.0/tcp/8080

Defensive patterns

Strategy: validation

Validate before calling

port=$(ipfs config Addresses.Gateway | grep -o '/tcp/[0-9]*' | cut -d/ -f3)
if ss -ltn "sport = :${port}" | grep -q LISTEN; then
  echo "port $port already in use"; exit 1
fi

Try / catch

if err != nil && strings.Contains(err.Error(), "manet.Listen") {
    log.Fatalf("gateway port unavailable; free the port or change Addresses.Gateway: %v", err)
}

Prevention

Pre-check the port with ss/lsof before starting the daemon.
Run only one daemon per IPFS_PATH (and per port set).
Use unprivileged ports (>1024); use socket activation for privileged ports.
In containers, publish/avoid collisions on 8080 explicitly.

When it happens

Trigger: manet.Listen(gatewayMaddr) fails: port already bound by another process or a running daemon, binding privileged port <1024 without privileges, invalid/unavailable interface, IPv6 not available.

Common situations: Second ipfs daemon started while one is running on 8080; another web server (nginx, Docker proxy) owns the port; `ipfs config Addresses.Gateway /ip4/0.0.0.0/tcp/80` on Linux without CAP_NET_BIND_SERVICE.

Related errors

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