What causes "serveHTTPApi: ConstructNode() failed: %s" in ipfs/kubo?

Read the inner error for the root cause; run `ipfs fsck` and repo migrations if a version mismatch is reported

serveHTTPApi: ConstructNode() failed: %s

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.

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)

Solutions

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

Defensive patterns

Strategy: try-catch

Validate before calling

// 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 */ }

Try / catch

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

Prevention

Run repo migrations after kubo upgrades (`ipfs fsck`)
Monitor datastore disk space
Never run two daemons on the same IPFS_PATH

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

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