serveHTTPGateway: invalid gateway address: %q (err: %s)

Error message

serveHTTPGateway: invalid gateway address: %q (err: %s)

What it means

Each value of cfg.Addresses.Gateway must parse as a valid libp2p multiaddr. serveHTTPGateway calls ma.NewMultiaddr on every configured gateway address and throws this error when parsing fails, naming the offending value and the parse error.

Source

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

	if err != nil {
		return nil, fmt.Errorf("serveHTTPGateway: GetConfig() failed: %s", err)
	}

	listeners, err := sockets.TakeListeners("io.ipfs.gateway")
	if err != nil {
		return nil, fmt.Errorf("serveHTTPGateway: socket activation failed: %s", err)
	}

	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())
	}

View on GitHub (pinned to 329838acdf)

Solutions

Set a valid multiaddr: `ipfs config Addresses.Gateway /ip4/0.0.0.0/tcp/8080`.
Print the current value with `ipfs config Addresses.Gateway` and correct the format (must start with /ip4/ or /ip6/ plus /tcp/ or /udp/).
Quote the value in the shell so slashes survive: `ipfs config Addresses.Gateway '/ip6/::/tcp/8080'`.
If an array is set via --json, validate each element parses as a multiaddr.

Example fix

// before
$ ipfs config Addresses.Gateway 0.0.0.0:8080
// after
$ ipfs config Addresses.Gateway /ip4/0.0.0.0/tcp/8080

Defensive patterns

Strategy: validation

Validate before calling

addr, _ := ipfsConfig.Get("Addresses.Gateway")
if _, err := multiaddr.NewMultiaddr(addr.(string)); err != nil {
    return fmt.Errorf("Addresses.Gateway must be a multiaddr like /ip4/0.0.0.0/tcp/8080: %w", err)
}

Try / catch

if err != nil && strings.Contains(err.Error(), "invalid gateway address") {
    log.Fatalf("bad Addresses.Gateway value; use e.g. /ip4/0.0.0.0/tcp/8080: %v", err)
}

Prevention

Always set gateway addresses with `ipfs config` (it validates multiaddr strings).
Quote values in the shell to protect slashes.
Never put ip:port or URLs into Addresses.Gateway.
Script config changes with --json and parse the array to validate each entry.

When it happens

Trigger: `ipfs config Addresses.Gateway` set to a non-multiaddr string such as "0.0.0.0:8080", ":8080", or a URL like "http://localhost:8080" instead of "/ip4/0.0.0.0/tcp/8080".

Common situations: Users copying an ip:port or URL into the config instead of a multiaddr; shell quoting mangling slashes in `ipfs config`; trailing whitespace or stray characters from manual edits.

Related errors

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