ipfs/kubo · error

fail to resolve the multiaddr:%s

Error message

fail to resolve the multiaddr:%s

What it means

parseIpfsAddr accepts a multiaddr target for `ipfs p2p` commands. If the address lacks an explicit /p2p/<peerid> component, kubo resolves it via madns (DNS/DNSADDR). When resolution succeeds but yields zero addresses, it returns this error because there is no usable endpoint.

Source

Thrown at core/commands/p2p.go:232

	multiaddr, err := ma.NewMultiaddr(addr)
	if err != nil {
		return nil, err
	}

	pi, err := peer.AddrInfoFromP2pAddr(multiaddr)
	if err == nil {
		return pi, nil
	}

	// resolve multiaddr whose protocol is not ma.P_IPFS
	ctx, cancel := context.WithTimeout(context.Background(), resolveTimeout)
	defer cancel()
	addrs, err := madns.Resolve(ctx, multiaddr)
	if err != nil {
		return nil, err
	}
	if len(addrs) == 0 {
		return nil, errors.New("fail to resolve the multiaddr:" + multiaddr.String())
	}
	var info peer.AddrInfo
	for _, addr := range addrs {
		taddr, id := peer.SplitAddr(addr)
		if id == "" {
			// not an ipfs addr, skipping.
			continue
		}
		switch info.ID {
		case "":
			info.ID = id
		case id:
		default:
			return nil, fmt.Errorf(
				"ambiguous multiaddr %s could refer to %s or %s",
				multiaddr,
				info.ID,
				id,

View on GitHub (pinned to 329838acdf)

Solutions

1. Verify the hostname's records: `dig example.com A` or `dig _dnsaddr.example.com TXT` must return at least one usable address.
2. Pass the target as a full ipfs multiaddr including the peer ID, e.g. `/ip4/x.x.x.x/tcp/4001/p2p/<peerid>`, to skip DNS resolution.
3. Correct typos in the multiaddr and confirm the remote peer is actually publishing its addresses.

Example fix

// before
ipfs p2p forward /p2p/x/1.0.0 /ip4/127.0.0.1/tcp/8080 /dns4/empty.example.com/tcp/443
// after
ipfs p2p forward /p2p/x/1.0.0 /ip4/127.0.0.1/tcp/8080 /dns4/peer.example.com/tcp/4001/p2p/<peerid>

addrs, err := net.LookupHost("peer.example.com")
if err != nil || len(addrs) == 0 {
    return errors.New("target host resolves to no addresses")
}

// error is a plain errors.New; match on message or pre-validate DNS
if err != nil && strings.HasPrefix(err.Error(), "fail to resolve the multiaddr:") {
    // check DNS records / switch to explicit /p2p/ multiaddr
}

When it happens

Trigger: Calling `ipfs p2p listen`/`forward` with a target multiaddr like `/dns4/example.com/tcp/443` whose DNS lookup succeeds but returns no records, or a dnsaddr that resolves to an empty set.

Common situations: DNS names with no A/AAAA/dnsaddr TXT records; a hostname that exists but points to nothing; DNS records removed while a script still references the target; resolveTimeout elapsed producing a resolution that returns empty rather than erroring upstream.

Related errors

• ambiguous multiaddr %s could refer to %s or %s
• non-resolvable API endpoint
• conn not found
• no local swarm address for migration node
• could not connect to migration peer %q: %s

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