{"record":{"id":"ec402570ed35d88d","repo":"ipfs/kubo","slug":"fail-to-resolve-the-multiaddr-s","errorCode":null,"errorMessage":"fail to resolve the multiaddr:%s","messagePattern":"fail to resolve the multiaddr:(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/commands/p2p.go","lineNumber":232,"sourceCode":"\tmultiaddr, err := ma.NewMultiaddr(addr)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tpi, err := peer.AddrInfoFromP2pAddr(multiaddr)\n\tif err == nil {\n\t\treturn pi, nil\n\t}\n\n\t// resolve multiaddr whose protocol is not ma.P_IPFS\n\tctx, cancel := context.WithTimeout(context.Background(), resolveTimeout)\n\tdefer cancel()\n\taddrs, err := madns.Resolve(ctx, multiaddr)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tif len(addrs) == 0 {\n\t\treturn nil, errors.New(\"fail to resolve the multiaddr:\" + multiaddr.String())\n\t}\n\tvar info peer.AddrInfo\n\tfor _, addr := range addrs {\n\t\ttaddr, id := peer.SplitAddr(addr)\n\t\tif id == \"\" {\n\t\t\t// not an ipfs addr, skipping.\n\t\t\tcontinue\n\t\t}\n\t\tswitch info.ID {\n\t\tcase \"\":\n\t\t\tinfo.ID = id\n\t\tcase id:\n\t\tdefault:\n\t\t\treturn nil, fmt.Errorf(\n\t\t\t\t\"ambiguous multiaddr %s could refer to %s or %s\",\n\t\t\t\tmultiaddr,\n\t\t\t\tinfo.ID,\n\t\t\t\tid,","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/commands/p2p.go#L214-L250","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the hostname's records: `dig example.com A` or `dig _dnsaddr.example.com TXT` must return at least one usable address.","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.","Correct typos in the multiaddr and confirm the remote peer is actually publishing its addresses."],"exampleFix":"// before\nipfs p2p forward /p2p/x/1.0.0 /ip4/127.0.0.1/tcp/8080 /dns4/empty.example.com/tcp/443\n// after\nipfs p2p forward /p2p/x/1.0.0 /ip4/127.0.0.1/tcp/8080 /dns4/peer.example.com/tcp/4001/p2p/<peerid>","handlingStrategy":"validation","validationCode":"addrs, err := net.LookupHost(\"peer.example.com\")\nif err != nil || len(addrs) == 0 {\n    return errors.New(\"target host resolves to no addresses\")\n}","typeGuard":null,"tryCatchPattern":"// error is a plain errors.New; match on message or pre-validate DNS\nif err != nil && strings.HasPrefix(err.Error(), \"fail to resolve the multiaddr:\") {\n    // check DNS records / switch to explicit /p2p/ multiaddr\n}","preventionTips":["Prefer full ipfs multiaddrs with an explicit /p2p/<peerid> component to bypass DNS resolution.","Verify dnsaddr/A records exist for hostnames used as p2p targets.","Alert on DNS record deletion for hosts referenced by tunneling configs."],"tags":["network","dns","multiaddr"],"backgroundTag":"multiaddr-resolution-failed","analyzedSha":"329838acdfafae224582930457efe80aa217afc0","analyzedAt":"2026-09-03T18:30:52.135Z","contentChangedAt":"2026-09-03T18:30:52.135Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}