{"record":{"id":"74a3251a433dc1b1","repo":"ipfs/kubo","slug":"servehttpgatewayoverlibp2p-constructnode-failed","errorCode":null,"errorMessage":"serveHTTPGatewayOverLibp2p: ConstructNode() failed: %s","messagePattern":"serveHTTPGatewayOverLibp2p: ConstructNode\\(\\) failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cmd/ipfs/kubo/daemon.go","lineNumber":1186,"sourceCode":"\t\tif err := node.Repo.SetGatewayAddr(addr); err != nil {\n\t\t\treturn nil, fmt.Errorf(\"serveHTTPGateway: SetGatewayAddr() failed: %w\", err)\n\t\t}\n\t}\n\n\tgo func() {\n\t\twg.Wait()\n\t\tclose(errc)\n\t}()\n\n\treturn errc, nil\n}\n\nconst gatewayProtocolID protocol.ID = \"/ipfs/gateway\" // FIXME: specify https://github.com/ipfs/specs/issues/433\n\nfunc serveTrustlessGatewayOverLibp2p(cctx *oldcmds.Context) (<-chan error, error) {\n\tnode, err := cctx.ConstructNode()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"serveHTTPGatewayOverLibp2p: ConstructNode() failed: %s\", err)\n\t}\n\tcfg, err := node.Repo.Config()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"could not read config: %w\", err)\n\t}\n\n\tif !cfg.Experimental.GatewayOverLibp2p {\n\t\terrCh := make(chan error)\n\t\tclose(errCh)\n\t\treturn errCh, nil\n\t}\n\n\topts := []corehttp.ServeOption{\n\t\tcorehttp.MetricsCollectionOption(\"libp2p-gateway\"),\n\t\tcorehttp.Libp2pGatewayOption(),\n\t\tcorehttp.VersionOption(),\n\t}\n","sourceCodeStart":1168,"sourceCodeEnd":1204,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/cmd/ipfs/kubo/daemon.go#L1168-L1204","documentation":"serveTrustlessGatewayOverLibp2p serves the trustless gateway over a libp2p stream handler (/ipfs/gateway protocol). It constructs the node first, and any error from cctx.ConstructNode() is wrapped with this message (note the message says serveHTTPGatewayOverLibp2p for historical reasons). This only runs when Experimental.GatewayOverLibp2p is enabled.","triggerScenarios":"cctx.ConstructNode() fails while Experimental.GatewayOverLibp2p is true: repo lock held, datastore open failure, libp2p host/identity issues, bad keystore or p2p config.","commonSituations":"Same repo used by two daemons (repo.lock); corrupted datastore; invalid identity key; enabling Experimental.GatewayOverLibp2p on a config with an unusable swarm setup.","solutions":["Inspect the inner error after the prefix; it names the construction failure (lock, datastore, identity).","Stop the competing daemon or remove a stale repo.lock when no daemon runs.","Validate the identity and swarm config: `ipfs config Identity.PeerID` and `ipfs config Addresses.Swarm`.","If you do not need trustless-over-libp2p, disable it: `ipfs config --json Experimental.GatewayOverLibp2p false`."],"exampleFix":"// before\n$ ipfs config --json Experimental.GatewayOverLibp2p true && ipfs daemon  # fails with lock held\n// after\n$ pkill -f \"ipfs daemon\" && ipfs daemon","handlingStrategy":"validation","validationCode":"if enabled, _ := ipfsConfig.Get(\"Experimental.GatewayOverLibp2p\"); enabled == true {\n    if _, err := os.Stat(filepath.Join(ipfsPath, \"repo.lock\")); err == nil && daemonRunning() {\n        return errors.New(\"repo locked by a running daemon\")\n    }\n}","typeGuard":null,"tryCatchPattern":"node, err := cctx.ConstructNode()\nif err != nil {\n    if strings.Contains(err.Error(), \"lock\") {\n        log.Fatal(\"stop the other daemon using this IPFS_PATH\")\n    }\n    log.Fatalf(\"ConstructNode for libp2p gateway failed: %v\", err)\n}","preventionTips":["Never start two daemons on the same IPFS_PATH.","Validate identity/swarm config before enabling Experimental.GatewayOverLibp2p.","Keep the experimental flag off unless trustless-over-libp2p is needed.","Clean stale repo.lock after abnormal exits."],"tags":["node-construction","libp2p","gateway","experimental"],"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"}