{"record":{"id":"7cb20cab41b472b2","repo":"ipfs/kubo","slug":"error-constructing-namesys-w","errorCode":null,"errorMessage":"error constructing namesys: %w","messagePattern":"error constructing namesys: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/coreapi/coreapi.go","lineNumber":239,"sourceCode":"\t\tif cs == 0 {\n\t\t\tcs = node.DefaultIpnsCacheSize\n\t\t}\n\t\tif cs < 0 {\n\t\t\treturn nil, errors.New(\"cannot specify negative resolve cache size\")\n\t\t}\n\n\t\tnsOptions := []namesys.Option{\n\t\t\tnamesys.WithDatastore(subAPI.repo.Datastore()),\n\t\t\tnamesys.WithDNSResolver(subAPI.dnsResolver),\n\t\t\tnamesys.WithCache(cs),\n\t\t\tnamesys.WithMaxCacheTTL(cfg.Ipns.MaxCacheTTL.WithDefault(config.DefaultIpnsMaxCacheTTL)),\n\t\t}\n\n\t\tsubAPI.routing = offlineroute.NewOfflineRouter(irouting.DHTValueDatastore(subAPI.repo.Datastore()), subAPI.recordValidator)\n\n\t\tsubAPI.namesys, err = namesys.NewNameSystem(subAPI.routing, nsOptions...)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"error constructing namesys: %w\", err)\n\t\t}\n\n\t\tsubAPI.peerstore = nil\n\t\tsubAPI.peerHost = nil\n\t\tsubAPI.recordValidator = nil\n\t}\n\n\tif settings.Offline || !settings.FetchBlocks {\n\t\tsubAPI.exchange = offlinexch.Exchange(subAPI.blockstore)\n\t\tsubAPI.blocks = bserv.New(subAPI.blockstore, subAPI.exchange,\n\t\t\tbserv.WriteThrough(cfg.Datastore.WriteThrough.WithDefault(config.DefaultWriteThrough)),\n\t\t)\n\t\tsubAPI.dag = dag.NewDAGService(subAPI.blocks)\n\t}\n\n\treturn subAPI, nil\n}\n","sourceCodeStart":221,"sourceCodeEnd":257,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/coreapi/coreapi.go#L221-L257","documentation":"Offline IPNS name resolution requires constructing a namesys.NameSystem over the offline routing (datastore-backed value store). If namesys.NewNameSystem fails with any of the supplied options, coreapi wraps the underlying cause with this message so the construction failure is attributed to namesys.","triggerScenarios":"Calling coreapi.NewNode with APIOptions{Offline: true} where the resulting namesys options (WithDatastore, WithDNSResolver, WithCache) or the offline router cause namesys.NewNameSystem to return an error, e.g. an invalid resolver or incompatible datastore.","commonSituations":"Injecting a custom DNS resolver that is nil or misconfigured; constructing an offline API node over a repo whose datastore failed mid-init; supplying a namesys option combination that namesys rejects.","solutions":["Inspect the wrapped %w cause to identify the actual namesys failure (datastore, resolver, or cache option).","Verify the repo datastore opens and is writable before constructing the offline node.","Ensure the provided dnsResolver is a non-nil, functional resolver.","Simplify to default options (only WithDatastore/WithDNSResolver) and add options back incrementally."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"if settings.Offline {\n    if api.repo.Datastore() == nil {\n        return errors.New(\"offline mode requires an open repo datastore\")\n    }\n    if dnsResolver == nil {\n        return errors.New(\"offline mode requires a DNS resolver\")\n}\n}","typeGuard":null,"tryCatchPattern":"subAPI.namesys, err = namesys.NewNameSystem(routing, nsOptions...)\nif err != nil {\n    return nil, fmt.Errorf(\"error constructing namesys: %w\", err) // inspect cause with errors.As/Is\n}","preventionTips":["Open and sanity-check the datastore before building an offline API node","Pass only well-tested namesys options; add custom resolvers gradually","Log the wrapped cause (%w) to distinguish resolver vs datastore failures"],"tags":["ipns","namesys","offline","initialization"],"backgroundTag":"component-construction-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"}