{"record":{"id":"c5822fd69cca799a","repo":"ipfs/kubo","slug":"error-constructing-namesys-w-c5822f","errorCode":null,"errorMessage":"error constructing namesys: %w","messagePattern":"error constructing namesys: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/corehttp/gateway.go","lineNumber":181,"sourceCode":"\t\tcs := cfg.Ipns.ResolveCacheSize\n\t\tif cs == 0 {\n\t\t\tcs = node.DefaultIpnsCacheSize\n\t\t}\n\t\tif cs < 0 {\n\t\t\treturn nil, fmt.Errorf(\"cannot specify negative resolve cache size\")\n\t\t}\n\n\t\tnsOptions := []namesys.Option{\n\t\t\tnamesys.WithDatastore(n.Repo.Datastore()),\n\t\t\tnamesys.WithDNSResolver(n.DNSResolver),\n\t\t\tnamesys.WithCache(cs),\n\t\t\tnamesys.WithMaxCacheTTL(cfg.Ipns.MaxCacheTTL.WithDefault(config.DefaultIpnsMaxCacheTTL)),\n\t\t}\n\n\t\tvsRouting = offlineroute.NewOfflineRouter(irouting.DHTValueDatastore(n.Repo.Datastore()), n.RecordValidator)\n\t\tnsys, err = namesys.NewNameSystem(vsRouting, nsOptions...)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"error constructing namesys: %w\", err)\n\t\t}\n\n\t\t// Gateway.NoFetch=true requires offline path resolver\n\t\t// to avoid fetching missing blocks during path traversal\n\t\tpathResolver = n.OfflineUnixFSPathResolver\n\t}\n\n\tbackend, err := gateway.NewBlocksBackend(bserv,\n\t\tgateway.WithValueStore(vsRouting),\n\t\tgateway.WithNameSystem(nsys),\n\t\tgateway.WithResolver(pathResolver),\n\t)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\treturn &offlineGatewayErrWrapper{gwimpl: backend}, nil\n}\n","sourceCodeStart":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/corehttp/gateway.go#L163-L199","documentation":"newGatewayBackend builds the IPNS name system (namesys) via namesys.NewNameSystem, wiring in the datastore, DNS resolver, cache size, and MaxCacheTTL. If namesys construction fails for any reason, the error is wrapped with 'error constructing namesys' and gateway startup aborts.","triggerScenarios":"Calling the gateway ServeOption (newGatewayBackend) when namesys.NewNameSystem returns an error — typically due to an invalid combination of Ipns options (e.g. bad ResolveCacheSize reaching namesys.WithCache), an unavailable Repo datastore, or a malformed DNSResolver configuration.","commonSituations":"Corrupted or locked datastore (repo in use by another daemon); invalid `Ipns.ResolveCacheSize`/`Ipns.MaxCacheTTL` config values; custom `DNSResolver` addresses in config that fail validation; running a gateway option chain against a partially initialized node in embedded usage.","solutions":["Inspect the wrapped (%w) cause in the full error message — it names the underlying failure (datastore, resolver, or option error).","Verify IPNS settings: `ipfs config --json Ipns` — ResolveCacheSize must be >= 0 and MaxCacheTTL a valid duration.","Ensure the repo datastore is accessible and not locked by another daemon process (`pkill -f 'ipfs daemon'`, then retry).","Check `DNSResolver` config entries are valid resolvers; reset with `ipfs config --json DNSResolver '{}'` if unsure.","Run `ipfs repo fsck` / verify repo health if the cause points at the datastore."],"exampleFix":"// before (invalid option reaching namesys)\nipfs config --json Ipns.ResolveCacheSize -5\n// error constructing namesys: ...\n\n// after\nipfs config --json Ipns.ResolveCacheSize 0 // default\nipfs daemon","handlingStrategy":"try-catch","validationCode":"// before gateway startup, sanity-check the inputs namesys consumes\nif cfg.Ipns.ResolveCacheSize < 0 { return errors.New(\"negative ResolveCacheSize\") }\nif _, err := time.ParseDuration(string(cfg.Ipns.MaxCacheTTL.WithDefault(config.DefaultIpnsMaxCacheTTL))); err != nil {\n    return fmt.Errorf(\"invalid Ipns.MaxCacheTTL: %w\", err)\n}\n// ensure the repo datastore opens\nif _, err := n.Repo.Datastore().Query(context.Background(), query.Query{}); err != nil {\n    return fmt.Errorf(\"datastore unavailable: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"_, err := corehttp.ListenAndServe(...) // or gateway option application\nvar initErr error\nif err != nil && strings.Contains(err.Error(), \"error constructing namesys\") {\n    // unwrap: log the %w cause, verify repo lock/datastore and Ipns config, then retry\n    log.Errorw(\"namesys init failed\", \"err\", err)\n    initErr = err\n}\nreturn initErr","preventionTips":["Validate the full `Ipns` config section before daemon start.","Ensure only one daemon runs per repo (stale lock causes datastore errors).","Keep DNSResolver config valid; reset to defaults when unsure.","Read the wrapped cause (%w) in the error message — it identifies the failing subsystem."],"tags":["gateway","ipns","namesys","initialization"],"backgroundTag":"component-initialization-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"}