ipfs/kubo · error

serveHTTPApi: ConstructNode() failed

Error message

serveHTTPApi: ConstructNode() failed: %s

What it means

serveHTTPApi constructs the full IPFS node (cctx.ConstructNode()) before serving the RPC API; any error during node construction (repo, datastore, blockstore, libp2p host, pnet key) is wrapped with this prefix and aborts daemon startup.

Solutions

1. Read the inner error for the root cause; run `ipfs fsck` and repo migrations if a version mismatch is reported
2. Ensure no other daemon holds the repo lock (`pkill -f 'ipfs daemon'`, remove $IPFS_PATH/repo.lock)
3. Check datastore disk space and permissions under $IPFS_PATH
4. Validate config (`ipfs config show`) for malformed Identity/Swarm entries

// preflight checks
if _, err := os.Stat(filepath.Join(ipfsPath, "repo.lock")); err == nil {
    // stale lock: ensure no daemon is running, then remove
}
// check disk space
if st, err := os.Statvfs(ipfsPath); err == nil && st.Bavail == 0 { /* disk full */ }

node, err := cctx.ConstructNode()
if err != nil {
    log.Errorf("node construction failed: %v", err)
    // inspect wrapped cause: migrations, datastore, identity, lock
    os.Exit(1)
}

When it happens

Trigger: `ipfs daemon` failing during node build: repo version mismatch requiring migration, corrupted datastore, invalid Identity.PrivKey, swarm key issues, or lock held by another process.

Common situations: Upgrading kubo across repo versions without `ipfs fsck migrate`; disk full or permissions on the datastore; corrupt config keys like Identity or Swarm; another daemon holding the repo lock.

Related errors

• serveHTTPApi: GetConfig() failed
• closing plugins
• private networking (swarm.key / LIBP2P_FORCE_PNET) does not…
• Routing.AcceleratedDHTClient option is set even tho…
• serveHTTPApi: invalid API address

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/fb6be27698cc3dd8. Report an issue: GitHub.

Appendix: source

Thrown at cmd/ipfs/kubo/daemon.go:904

		corehttp.WebUIOption,
		gatewayOpt,
		corehttp.VersionOption(),
		defaultMux("/debug/vars"),
		defaultMux("/debug/pprof/"),
		defaultMux("/debug/stack"),
		corehttp.MutexFractionOption("/debug/pprof-mutex/"),
		corehttp.BlockProfileRateOption("/debug/pprof-block/"),
		corehttp.MetricsScrapingOption("/debug/metrics/prometheus"),
		corehttp.LogOption(),
	}

	if len(cfg.Gateway.RootRedirect) > 0 {
		opts = append(opts, corehttp.RedirectOption("", cfg.Gateway.RootRedirect))
	}

	node, err := cctx.ConstructNode()
	if err != nil {
		return nil, fmt.Errorf("serveHTTPApi: ConstructNode() failed: %s", err)
	}

	// Buffer channel to prevent deadlock when multiple servers write errors simultaneously
	errc := make(chan error, len(listeners))
	var wg sync.WaitGroup

	// Start all servers and wait for them to be ready before writing api file.
	// This prevents race conditions where external tools (like systemd path units)
	// see the file and try to connect before servers can accept connections.
	if len(listeners) > 0 {
		readyChannels := make([]chan struct{}, len(listeners))
		for i, lis := range listeners {
			readyChannels[i] = make(chan struct{})
			ready := readyChannels[i]
			wg.Go(func() {
				errc <- corehttp.ServeWithReady(node, manet.NetListener(lis), ready, opts...)
			})
		}

View on GitHub (pinned to 329838acdf)