ipfs/kubo · error

failed to configure private network: %s

Error message

failed to configure private network: %s

What it means

When a private network is configured (Swarm.Key exists in the repo), Kubo decodes the swarm key file as a libp2p V1 pre-shared key (pnet.DecodeV1PSK). If the file exists but its contents are not a valid 32-byte base16 PSK in the expected format, node construction fails wrapped with this error.

Source

Thrown at core/node/libp2p/pnet.go:29

	"github.com/libp2p/go-libp2p"
	"github.com/libp2p/go-libp2p/core/host"
	"github.com/libp2p/go-libp2p/core/pnet"
	"go.uber.org/fx"
	"golang.org/x/crypto/salsa20"
	"golang.org/x/crypto/sha3"
)

type PNetFingerprint []byte

func PNet(repo repo.Repo) (opts Libp2pOpts, fp PNetFingerprint, err error) {
	swarmkey, err := repo.SwarmKey()
	if err != nil || swarmkey == nil {
		return opts, nil, err
	}

	psk, err := pnet.DecodeV1PSK(bytes.NewReader(swarmkey))
	if err != nil {
		return opts, nil, fmt.Errorf("failed to configure private network: %s", err)
	}

	opts.Opts = append(opts.Opts, libp2p.PrivateNetwork(psk))

	return opts, pnetFingerprint(psk), nil
}

func PNetChecker(repo repo.Repo, ph host.Host, lc fx.Lifecycle) error {
	// TODO: better check?
	swarmkey, err := repo.SwarmKey()
	if err != nil || swarmkey == nil {
		return err
	}

	done := make(chan struct{})
	lc.Append(fx.Hook{
		OnStart: func(_ context.Context) error {
			go func() {

View on GitHub (pinned to 329838acdf)

Solutions

1. Regenerate or fix Swarm.Key to the canonical format: a line `KEY_TYPE` may be omitted and the body must be 64 hex chars, e.g. `echo -e "/key/swarm/psk/1.0.0/\n/base16/$(openssl rand -hex 32)" > "$IPFS_PATH/swarm.key"`
2. Strip any BOM, CRLF, or trailing garbage from the existing swarm.key file (ensure plain ASCII with newline-separated header and key)
3. Verify which file is being used (`ipfs config --json Swarm` / check repo path) — you may be pointing at the wrong or corrupted key file

Example fix

// before (swarm.key)
c29tZXRoaW5nLXNob3J0ZXIta2V5
// after (swarm.key)
/key/swarm/psk/1.0.0/
/base16/0a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9

b, err := os.ReadFile(keyPath)
if err != nil { return err }
if _, err := pnet.DecodeV1PSK(bytes.NewReader(b)); err != nil {
    return fmt.Errorf("swarm key %s is not a valid V1 PSK: %w", keyPath, err)
}

When it happens

Trigger: Starting the daemon with a repo that contains a Swarm.Key file whose contents fail PSK decoding — wrong format, extra whitespace/BOM, truncated hex, or a key generated by a different/incompatible tool.

Common situations: Generating the swarm key by hand (correct format: a 32-byte hex key, optionally with the /key/swarm/psk/1.0.0/ multibase header); copying the key with newline/encoding corruption; mixing clusters' key files; placing a non-PSK file at Swarm.Key path.

Related errors

• private networking (swarm.key / LIBP2P_FORCE_PNET) does not
• unrecognized Swarm.ConnMgr.Type: %q
• unknown pubsub router %s
• incorrectly formatted address filter in config: %s
• unrecognized reachability option: %s

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