What causes "constructing the node (see log for full detail): %w" in ipfs/kubo?

Check the node logs — the real error was logged with full detail before this wrapper is returned.

constructing the node (see log for full detail): %w

Error message

constructing the node (see log for full detail): %w

What it means

When fx fails to construct the node, NewNode delegates to logAndUnwrapFxError, which iteratively unwraps fx's InternalError/extracted errors to reach the innermost root cause, logs the full detail, and returns it wrapped as 'constructing the node (see log for full detail)'. It signals that an fx-provided dependency (e.g. blockservice, pnet, routing) failed during graph construction.

Source

Thrown at core/builder.go:189

	err := fxAppErr
	for {
		extractedErr := dig.RootCause(err)
		// Note that the `RootCause` name is misleading as it just unwraps only
		// *one* error layer at a time, so we need to continuously call it.
		if !reflect.TypeOf(extractedErr).Comparable() {
			// Some internal errors are not comparable (e.g., `dig.errMissingTypes`
			// which is a slice) and we can't go further.
			break
		}
		if extractedErr == err {
			// We didn't unwrap any new error in the last call, reached the innermost one.
			break
		}
		err = extractedErr
	}

	return fmt.Errorf("constructing the node (see log for full detail): %w", err)
}

View on GitHub (pinned to 329838acdf)

Solutions

Check the node logs — the real error was logged with full detail before this wrapper is returned.
Unwrap with errors.Unwrap repeatedly (the function already does this; inspect the final cause with `%+v`).
Fix the underlying dependency failure: verify repo/datastore, swarm.key, and config values.
Rebuild/restart; if caused by a plugin, disable the offending plugin.

Example fix

// before
n, err := core.NewNode(ctx, cfg)
if err != nil { return err } // opaque
// after
if err != nil {
    for e := err; e != nil; e = errors.Unwrap(e) {
        fmt.Println(e) // find innermost cause
    }
}

Defensive patterns

Strategy: try-catch

Validate before calling

// validate config parseable before node build
var cfg config.Config
if err := json.Unmarshal(cfgBytes, &cfg); err != nil {
    return fmt.Errorf("invalid config: %w", err)
}

Type guard

func isNodeConstructionError(err error) bool {
    return err != nil && strings.Contains(err.Error(), "constructing the node")
}

Try / catch

n, err := core.NewNode(ctx, cfg)
if err != nil && isNodeConstructionError(err) {
    // full detail is in the node log; also walk the unwrap chain
    for e := err; e != nil; e = errors.Unwrap(e) {
        log.Println(e)
    }
    cancel()
    return err
}

Prevention

Always capture node logs at debug/error level during startup — the root cause is logged there
Validate swarm.key and repo permissions before starting private-network nodes
Test node construction in CI with a throwaway IPFS_PATH

When it happens

Trigger: core.NewNode reaching fx.New(opts...) and the fx app failing to build — e.g. a constructor returning an error (bad private network key, datastore open failure, invalid config value consumed by a constructor).

Common situations: Daemon startup failure due to corrupted repo, swarm key mismatch (pnet), or invalid config consumed by a service constructor; library users constructing online nodes on machines with missing resources.

Related errors

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