{"record":{"id":"745bf7253b766ccc","repo":"ipfs/kubo","slug":"non-resolvable-api-endpoint","errorCode":null,"errorMessage":"non-resolvable API endpoint","messagePattern":"non-resolvable API endpoint","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/ipfs/kubo/start.go","lineNumber":465,"sourceCode":"\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\treturn stopProfilingFunc, nil\n\t}\n\treturn func() {}, nil\n}\n\nfunc resolveAddr(ctx context.Context, addr ma.Multiaddr) (ma.Multiaddr, error) {\n\tctx, cancelFunc := context.WithTimeout(ctx, 10*time.Second)\n\tdefer cancelFunc()\n\n\taddrs, err := dnsResolver.Resolve(ctx, addr)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tif len(addrs) == 0 {\n\t\treturn nil, errors.New(\"non-resolvable API endpoint\")\n\t}\n\n\treturn addrs[0], nil\n}\n\ntype nopWriter struct {\n\tio.Writer\n}\n\nfunc (nw nopWriter) Close() error {\n\treturn nil\n}\n\nfunc getRemoteVersion(exe cmds.Executor) (*semver.Version, error) {\n\tctx, cancel := context.WithDeadline(context.Background(), time.Now().Add(time.Second*30))\n\tdefer cancel()\n\n\treq, err := cmds.NewRequest(ctx, []string{\"version\"}, nil, nil, nil, Root)","sourceCodeStart":447,"sourceCodeEnd":483,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/cmd/ipfs/kubo/start.go#L447-L483","documentation":"resolveAddr resolves DNS entries in the API multiaddr (e.g. /dns4/, /dns6/) using a 10-second-timeout DNS resolver. If the DNS resolution succeeds at the protocol level but returns zero addresses, it fails with 'non-resolvable API endpoint'. It is raised in resolveAddr, which makeExecutor calls to validate the API address before dialing.","triggerScenarios":"Using `--api /dns4/somehost/tcp/5001` (or /dns6) where somehost has no A/AAAA records; a hostname whose DNS records were removed while the api file still references it; DNS returning NXDOMAIN/NODATA that the resolver maps to an empty result set.","commonSituations":"Pointing --api at a stale hostname after infrastructure changed (container removed, DNS record deleted); typos in the hostname; split-horizon DNS where the record exists publicly but not from the node's resolver; IPv6-only hostname used with /dns4 (or vice versa).","solutions":["Replace the dns4/dns6 multiaddr with a direct IP: `--api /ip4/<addr>/tcp/5001`.","Verify the hostname resolves: `dig somehost A` / `dig somehost AAAA`, and fix DNS or use the other of dns4/dns6.","Check the daemon host's current address (`ipfs config Addresses.API`) and update the api file at $IPFS_PATH/api or the --api flag accordingly."],"exampleFix":"# before\nipfs --api /dns4/old-container/tcp/5001 id\n# after\nipfs --api /ip4/127.0.0.1/tcp/5001 id","handlingStrategy":"retry","validationCode":"u, _ := ma.NewMultiaddr(apiStr)\nif h, err := u.ValueForProtocol(ma.P_DNS4); err == nil {\n    if addrs, err := net.LookupHost(h); err != nil || len(addrs) == 0 {\n        return fmt.Errorf(\"api host %q does not resolve\", h)\n    }\n}","typeGuard":"func apiHostResolves(addr ma.Multiaddr) bool {\n    for _, p := range []int{ma.P_DNS, ma.P_DNS4, ma.P_DNS6} {\n        if h, err := addr.ValueForProtocol(p); err == nil {\n            addrs, err := net.LookupHost(h)\n            return err == nil && len(addrs) > 0\n        }\n    }\n    return true // no DNS component\n}","tryCatchPattern":"out, err := run(\"ipfs\", args...)\nif err != nil && strings.Contains(out+err.Error(), \"non-resolvable API endpoint\") {\n    time.Sleep(2 * time.Second) // tolerate transient DNS\n    out, err = run(\"ipfs\", args...)\n}","preventionTips":["Use IP multiaddrs or stable DNS names for the daemon API; avoid ephemeral container hostnames.","Monitor DNS records for hosts referenced by the api file.","Prefer /dns4 vs /dns6 deliberately based on the record family that actually exists.","Refresh $IPFS_PATH/api after infrastructure changes; don't hand-copy stale hostnames."],"tags":["network","dns","kubo","api-address"],"backgroundTag":"dns-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"}