{"record":{"id":"2bdf636055388ba7","repo":"ipfs/kubo","slug":"servehttpgateway-constructnode-failed-s","errorCode":null,"errorMessage":"serveHTTPGateway: ConstructNode() failed: %s","messagePattern":"serveHTTPGateway: ConstructNode\\(\\) failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cmd/ipfs/kubo/daemon.go","lineNumber":1134,"sourceCode":"\t\tcorehttp.VersionOption(),\n\t\tcorehttp.CheckVersionOption(),\n\t}\n\n\tif cfg.Experimental.P2pHttpProxy {\n\t\topts = append(opts, corehttp.P2PProxyOption())\n\t}\n\n\tif cfg.Gateway.ExposeRoutingAPI.WithDefault(config.DefaultExposeRoutingAPI) {\n\t\topts = append(opts, corehttp.RoutingOption())\n\t}\n\n\tif len(cfg.Gateway.RootRedirect) > 0 {\n\t\topts = append(opts, corehttp.RedirectOption(\"\", cfg.Gateway.RootRedirect))\n\t}\n\n\tnode, err := cctx.ConstructNode()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"serveHTTPGateway: ConstructNode() failed: %s\", err)\n\t}\n\n\t// Buffer channel to prevent deadlock when multiple servers write errors simultaneously\n\terrc := make(chan error, len(listeners))\n\tvar wg sync.WaitGroup\n\n\t// Start all servers and wait for them to be ready before writing gateway file.\n\t// This prevents race conditions where external tools (like systemd path units)\n\t// see the file and try to connect before servers can accept connections.\n\tif len(listeners) > 0 {\n\t\treadyChannels := make([]chan struct{}, len(listeners))\n\t\tfor i, lis := range listeners {\n\t\t\treadyChannels[i] = make(chan struct{})\n\t\t\tready := readyChannels[i]\n\t\t\twg.Go(func() {\n\t\t\t\terrc <- corehttp.ServeWithReady(node, manet.NetListener(lis), ready, opts...)\n\t\t\t})\n\t\t}","sourceCodeStart":1116,"sourceCodeEnd":1152,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/cmd/ipfs/kubo/daemon.go#L1116-L1152","documentation":"serveHTTPGateway builds the full IPFS node via cctx.ConstructNode() before serving gateway requests. Any error constructing the node (repo lock, datastore open, blockstore init, p2p host setup) is wrapped with this message and daemon startup aborts.","triggerScenarios":"cctx.ConstructNode() returns an error: repo already locked by another daemon, datastore corruption or unsupported type, bad Datastore config, key/keystore problems, failure initializing libp2p services.","commonSituations":"Two daemons on the same IPFS_PATH (repo.lock held); corrupted flatfs/badgerds datastore after crash; bad Experimental flags or Datastore.Spec changes; insufficient disk or bad ownership of the repo.","solutions":["Check for and stop an already-running daemon holding repo.lock: pkill -f \"ipfs daemon\", or remove a stale $IPFS_PATH/repo.lock if no daemon is running.","Run `ipfs repo fsck` / inspect datastore errors in the wrapped message; restore from backup if the datastore is corrupted.","Validate config changes with `ipfs config show` (especially Datastore.* and Experimental.* keys) and revert bad edits.","Fix repo directory permissions/disk space so the datastore can be opened read-write."],"exampleFix":"// before\n$ ipfs daemon & ipfs daemon\nConstructNode() failed: lock: someone already has the lock\n// after\n$ pkill -f \"ipfs daemon\"\n$ rm -f $IPFS_PATH/repo.lock   # only if no daemon runs\n$ ipfs daemon","handlingStrategy":"validation","validationCode":"if [ -f \"$IPFS_PATH/repo.lock\" ] && ! pgrep -f 'ipfs daemon' >/dev/null; then\n  echo 'stale lock, no daemon running'; rm -f \"$IPFS_PATH/repo.lock\"\nfi","typeGuard":null,"tryCatchPattern":"node, err := cctx.ConstructNode()\nif err != nil {\n    if strings.Contains(err.Error(), \"lock\") {\n        log.Fatal(\"another daemon holds repo.lock; stop it first\")\n    }\n    log.Fatalf(\"node construction failed: %v\", err)\n}","preventionTips":["One daemon per repo; use pkill or `ipfs shutdown` before restarting.","Let the daemon shut down gracefully so locks are released.","Test datastore config changes in a copy of the repo first.","Monitor disk space and repo permissions in deployment."],"tags":["node-construction","repo-lock","datastore","daemon"],"backgroundTag":"repo-locked","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"}