{"record":{"id":"9e6c57110aab3106","repo":"ipfs/kubo","slug":"could-not-resolve-name","errorCode":null,"errorMessage":"could not resolve name","messagePattern":"could not resolve name","errorType":"exception","errorClass":"ErrResolveFailed","httpStatus":null,"severity":"error","filePath":"core/coreiface/name.go","lineNumber":12,"sourceCode":"package iface\n\nimport (\n\t\"context\"\n\t\"errors\"\n\n\t\"github.com/ipfs/boxo/ipns\"\n\t\"github.com/ipfs/boxo/path\"\n\t\"github.com/ipfs/kubo/core/coreiface/options\"\n)\n\nvar ErrResolveFailed = errors.New(\"could not resolve name\")\n\ntype IpnsResult struct {\n\tpath.Path\n\tErr error\n}\n\n// NameAPI specifies the interface to IPNS.\n//\n// IPNS is a PKI namespace, where names are the hashes of public keys, and the\n// private key enables publishing new (signed) values. In both publish and\n// resolve, the default name used is the node's own PeerID, which is the hash of\n// its public key.\n//\n// You can use .Key API to list and generate more names and their respective keys.\ntype NameAPI interface {\n\t// Publish announces new IPNS name\n\tPublish(ctx context.Context, path path.Path, opts ...options.NamePublishOption) (ipns.Name, error)\n","sourceCodeStart":1,"sourceCodeEnd":30,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/coreiface/name.go#L1-L30","documentation":"`ErrResolveFailed` is the sentinel error signaling that an IPNS/DNSLink name could not be resolved to a path. `Resolve` and the internal `loadRoot` return it when the namesys lookup fails (record not found, invalid record, timeout) and, as in core/coreapi/name.go, it is used as a base error that gets wrapped with more specific causes before returning.","triggerScenarios":"Calling `api.Name().Resolve(ctx, name)` for an IPNS name with no published record, an expired/invalid record, or a DNSLink domain without a TXT record; also returned by the mock namesys in gateway tests when a name is missing from the fixture map.","commonSituations":"`ipfs name resolve <peerid>` for a name that was never published or whose record expired; DNSLink domains missing `_dnslink.` TXT entries; network partitions/timeouts during DHT lookup of the IPNS record; stale local caches with republisher turned off.","solutions":["Verify the name actually resolves: check the IPNS record (`ipfs routing get /ipns/<name>` or `ipfs name resolve --norepensive`... i.e. re-run with `ipfs name resolve -r`/inspect via `ipfs dht findvalue /ipns/<name>`) and confirm DNSLink TXT records with `dig TXT _dnslink.<domain>`.","Republish the IPNS record from the owning key (`ipfs name publish <path>`) if it expired or was never published.","Increase timeout/retry around resolution (records may take time to propagate) and ensure the daemon is online; check `errors.Is(err, coreiface.ErrResolveFailed)` to distinguish resolution failure from other errors."],"exampleFix":"// before\np, err := api.Name().Resolve(ctx, name)\nif err != nil { return err }\n// after\np, err := api.Name().Resolve(ctx, name)\nif err != nil {\n    if errors.Is(err, coreiface.ErrResolveFailed) {\n        return fmt.Errorf(\"%w: check record exists/expired and DNSLink TXT\", err)\n    }\n    return err\n}","handlingStrategy":"retry","validationCode":"// Before resolving, verify the record exists:\n// - IPNS: `ipfs name resolve <name>` or `ipfs routing get /ipns/<name>`\n// - DNSLink: `dig TXT _dnslink.<domain>` returns a dnslink=/ipfs/... entry","typeGuard":null,"tryCatchPattern":"p, err := api.Name().Resolve(ctx, name)\nif err != nil {\n    if errors.Is(err, coreiface.ErrResolveFailed) {\n        // retry with backoff; records may still be propagating\n        p, err = resolveWithRetry(ctx, name, 3)\n    }\n    if err != nil { return fmt.Errorf(\"resolve %s: %w\", name, err) }\n}","preventionTips":["Verify IPNS records are published and not expired (check republish period)","Confirm DNSLink TXT records with dig before resolving domains","Add timeout and retry with backoff for resolution over DHT","Distinguish ErrResolveFailed with errors.Is to give actionable user messages"],"tags":["ipns","dnslink","resolution","coreapi","namesys"],"backgroundTag":"name-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"}