ipfs/kubo · error

serveHTTPApi: invalid API address: %q (err: %s)

Error message

serveHTTPApi: invalid API address: %q (err: %s)

What it means

A configured or --api-provided API address string could not be parsed as a multiaddr (ma.NewMultiaddr failed). %q is the raw address string and %s the parse error; the daemon rejects it instead of guessing, so a typo like a missing slash or bad protocol name blocks API startup.

Source

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

	}

	apiAddrs := make([]string, 0, 2)
	apiAddr, _ := req.Options[commands.ApiOption].(string)
	if apiAddr == "" {
		apiAddrs = cfg.Addresses.API
	} else {
		apiAddrs = append(apiAddrs, apiAddr)
	}

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

	for _, addr := range apiAddrs {
		apiMaddr, err := ma.NewMultiaddr(addr)
		if err != nil {
			return nil, fmt.Errorf("serveHTTPApi: invalid API address: %q (err: %s)", addr, err)
		}
		if listenerAddrs[string(apiMaddr.Bytes())] {
			continue
		}

		apiLis, err := manet.Listen(apiMaddr)
		if err != nil {
			return nil, fmt.Errorf("serveHTTPApi: manet.Listen(%s) failed: %s", apiMaddr, err)
		}

		listenerAddrs[string(apiMaddr.Bytes())] = true
		listeners = append(listeners, apiLis)
	}

	if len(cfg.API.Authorizations) > 0 && len(listeners) > 0 {
		fmt.Printf("RPC API access is limited by the rules defined in API.Authorizations\n")
	}

View on GitHub (pinned to 329838acdf)

Solutions

1. Correct the offending entry in Addresses.API to a valid multiaddr, e.g. /ip4/127.0.0.1/tcp/5001
2. Use `ipfs config Addresses.API` to set values instead of editing JSON by hand
3. Validate with `ipfs config show | jq '.Addresses.API'` and fix malformed entries

Example fix

// before
"Addresses": { "API": ["127.0.0.1:5001"] }
// after
"Addresses": { "API": ["/ip4/127.0.0.1/tcp/5001"] }

for _, addr := range apiAddrs {
    if _, err := multiaddr.NewMultiaddr(addr); err != nil {
        return fmt.Errorf("invalid Addresses.API entry %q: %v", addr, err)
    }
}

When it happens

Trigger: `ipfs daemon` when config Addresses.API contains a string that ma.NewMultiaddr rejects (e.g. missing /ip4//tcp scheme, stray characters, typo like "/ip4/0.0.0.0:5001").

Common situations: Hand-edited config merging host:port syntax instead of multiaddr syntax; scripts writing Addresses.API with wrong format; copy-paste from non-kubo tools.

Related errors

• serveHTTPApi: GetConfig() failed: %s
• private networking (swarm.key / LIBP2P_FORCE_PNET) does not
• Routing.AcceleratedDHTClient option is set even tho Routing.
• serveHTTPApi: socket activation failed: %s
• serveHTTPApi: manet.Listen(%s) failed: %s

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