ipfs/kubo · error

ambiguous multiaddr %s could refer to %s or %s

Error message

ambiguous multiaddr %s could refer to %s or %s

What it means

After resolving a target multiaddr, parseIpfsAddr splits each resolved address into transport address and peer ID. If different resolved addresses carry different peer IDs, the original multiaddr is ambiguous - it could refer to two distinct peers - so kubo refuses to pick one and returns this error naming both IDs.

Source

Thrown at core/commands/p2p.go:246

	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,
			)
		}
		info.Addrs = append(info.Addrs, taddr)
	}
	return &info, nil
}

var p2pListenCmd = &cmds.Command{
	Status: cmds.Experimental,
	Helptext: cmds.HelpText{
		Tagline: "Create libp2p service.",
		ShortDescription: `
Create a libp2p protocol handler that forwards incoming connections to
<target-address>.

View on GitHub (pinned to 329838acdf)

Solutions

1. Use one explicit target per peer: pass `/ip4/x.x.x.x/tcp/4001/p2p/<peerid>` with the specific peer ID you want.
2. Fix the dnsaddr/DNS records so all resolved addresses carry the same peer ID.
3. If multiple peers are intentional, issue one p2p forward per peer instead of one ambiguous multiaddr.

Example fix

// before
ipfs p2p forward /p2p/x/1.0.0 :8080 /dnsaddr/mixed.example.com   # resolves to two peer IDs
// after
ipfs p2p forward /p2p/x/1.0.0 :8080 /ip4/203.0.113.5/tcp/4001/p2p/12D3KooW...

// resolve first, then verify a single peer ID across results
resolved, _ := madns.Resolve(ctx, ma)
ids := map[string]struct{}{}
for _, a := range resolved {
    if _, id := peer.SplitAddr(a); id != "" {
        ids[id.String()] = struct{}{}
    }
}
if len(ids) > 1 {
    return errors.New("ambiguous target: multiple peer IDs")
}

When it happens

Trigger: Calling an `ipfs p2p` command with a target like a dnsaddr or round-robin DNS name whose resolved addresses embed two different /p2p/<peerid> values.

Common situations: A dnsaddr TXT record listing multiple different peers; a load-balanced hostname mixing peers; stale/mixed DNS records after rekeying a node; copy-pasting a multiaddr that concatenates addresses of two nodes.

Related errors

• fail to resolve the multiaddr:%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/aa7b37d48f6baff0. Report an issue: GitHub.