ipfs/kubo · error

serveHTTPGateway: manet.ToNetAddr() failed: %w

Error message

serveHTTPGateway: manet.ToNetAddr() failed: %w

What it means

After listeners are ready, kubo converts the first gateway listener's multiaddr to a TCP/UDP net address via manet.ToNetAddr to advertise it. This error is thrown if that conversion fails, which normally indicates the listener's multiaddr is not a network-translatable form (unexpected transport).

Source

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

			ready := readyChannels[i]
			wg.Go(func() {
				errc <- corehttp.ServeWithReady(node, manet.NetListener(lis), ready, opts...)
			})
		}

		// Wait for all listeners to be ready or any to fail
		for _, ready := range readyChannels {
			select {
			case <-ready:
				// This listener is ready
			case err := <-errc:
				return nil, fmt.Errorf("serveHTTPGateway: %w", err)
			}
		}

		addr, err := manet.ToNetAddr(rewriteMaddrToUseLocalhostIfItsAny(listeners[0].Multiaddr()))
		if err != nil {
			return nil, fmt.Errorf("serveHTTPGateway: manet.ToNetAddr() failed: %w", err)
		}
		if err := node.Repo.SetGatewayAddr(addr); err != nil {
			return nil, fmt.Errorf("serveHTTPGateway: SetGatewayAddr() failed: %w", err)
		}
	}

	go func() {
		wg.Wait()
		close(errc)
	}()

	return errc, nil
}

const gatewayProtocolID protocol.ID = "/ipfs/gateway" // FIXME: specify https://github.com/ipfs/specs/issues/433

func serveTrustlessGatewayOverLibp2p(cctx *oldcmds.Context) (<-chan error, error) {
	node, err := cctx.ConstructNode()

View on GitHub (pinned to 329838acdf)

Solutions

1. Set Addresses.Gateway to a standard TCP multiaddr: `ipfs config Addresses.Gateway /ip4/127.0.0.1/tcp/8080`.
2. Inspect `ipfs config Addresses.Gateway` and remove any /unix/ or non-IP entries.
3. If you need multiple gateways, list only /ip4|/ip6 + /tcp entries in the array.
4. Re-run after fixing; conversion always succeeds for plain IP+TCP multiaddrs.

Example fix

// before
$ ipfs config Addresses.Gateway /unix/tmp/gw.sock
// after
$ ipfs config Addresses.Gateway /ip4/127.0.0.1/tcp/8080

gw, _ := ipfsConfig.Get("Addresses.Gateway")
for _, a := range gw.([]string) {
    if !strings.HasPrefix(a, "/ip4/") && !strings.HasPrefix(a, "/ip6/") {
        return fmt.Errorf("gateway addr %q must be an IP+TCP multiaddr", a)
    }
}

if err != nil && strings.Contains(err.Error(), "manet.ToNetAddr() failed") {
    log.Fatalf("unsupported gateway multiaddr; use /ip4|/ip6 + /tcp form: %v", err)
}

When it happens

Trigger: manet.ToNetAddr() fails on rewriteMaddrToUseLocalhostIfItsAny(listeners[0].Multiaddr()): the configured gateway multiaddr is a form manet cannot map to a net.Addr (e.g., unix-socket or other non-IP multiaddr in Addresses.Gateway).

Common situations: Configuring Addresses.Gateway with a /unix/ or other exotic multiaddr; custom transports in config that the gateway HTTP server does not support; config edited by tooling expecting only /ip4|/ip6 tcp forms.

Related errors

• serveHTTPGateway: invalid gateway address: %q (err: %s)
• serveHTTPApi: invalid API address: %q (err: %s)
• serveHTTPGateway: GetConfig() failed: %s
• could not read config: %w
• cannot specify negative resolve cache size

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