ipfs/kubo · error

cannot set Identity.PeerID to a value that does not match th

Error message

cannot set Identity.PeerID to a value that does not match the node's private key; use 'ipfs key rotate' to change the node identity

What it means

`ipfs config Identity.PeerID <value>` validates that the given peer ID is a valid peer.Decode result AND equals the peer ID derived from the node's private key (nodePeerID(r)). Kubo throws this because Identity.PeerID is cryptographically bound to the PrivKey stored in the repo; setting an arbitrary value would produce a node whose advertised identity cannot be proven, so the write is refused.

Source

Thrown at core/commands/config.go:140

			// PeerID in any standard form (base58 or CIDv1), compare decoded
			// IDs rather than strings, store the canonical base58 string kubo
			// writes elsewhere, and point a mismatched value at the supported
			// way to change the identity.
			if strings.EqualFold(key, "identity.peerid") {
				candidate := value
				if parseJSON, _ := req.Options[configJSONOptionName].(bool); parseJSON {
					var s string
					if err := json.Unmarshal([]byte(value), &s); err == nil {
						candidate = s
					}
				}
				id, err := nodePeerID(r)
				if err != nil {
					return err
				}
				got, err := peer.Decode(candidate)
				if err != nil || got != id {
					return errors.New("cannot set Identity.PeerID to a value that does not match the node's private key; use 'ipfs key rotate' to change the node identity")
				}
				output, err = setConfig(r, key, id.String())
				if err != nil {
					return err
				}
				return cmds.EmitOnce(res, output)
			}

			if parseJSON, _ := req.Options[configJSONOptionName].(bool); parseJSON {
				var jsonVal any
				if err := json.Unmarshal([]byte(value), &jsonVal); err != nil {
					err = fmt.Errorf("failed to unmarshal json. %s", err)
					return err
				}

				output, err = setConfig(r, key, jsonVal)
			} else if isbool, _ := req.Options[configBoolOptionName].(bool); isbool {
				output, err = setConfig(r, key, value == "true")

View on GitHub (pinned to 329838acdf)

Solutions

1. If you intend to change the node identity, run `ipfs key rotate` instead, which regenerates the keypair and updates Identity consistently
2. If you meant to keep the existing identity, leave Identity.PeerID alone; it is set automatically at `ipfs init`
3. If you are copying a config to another machine, copy the full repo (including the keystore/private key) or accept that the peer ID must change
4. Verify the correct value with `ipfs id` and use exactly that string if you must set it explicitly

Example fix

// before
$ ipfs config Identity.PeerID 12D3KooWOtherNodeID
error: cannot set Identity.PeerID...
// after
$ ipfs key rotate --old-key-type=ed25519 # generates a new key + matching PeerID
$ ipfs id -f '<id>'

id=$(ipfs id -f '<id>'); if [ "$wanted" != "$id" ]; then echo "PeerID must be $id (or use 'ipfs key rotate')"; exit 1; fi

func isNodePeerID(cfg *config.Config, candidate string) bool {
	got, err := peer.Decode(candidate)
	return err == nil && got.Pretty() == cfg.Identity.PeerID
}

When it happens

Trigger: Running `ipfs config Identity.PeerID <id>` (or `--json`) with an ID that is not the node's own peer ID, a typo'd/copied peer ID, or an ID from another node; also a malformed peer ID string that fails peer.Decode (err != nil triggers the same branch).

Common situations: Migrating a config file between nodes by copy-pasting Identity sections; trying to 'claim' a peer ID without moving the corresponding private key; hand-editing config after `ipfs init` on a machine restored from backup where the key was regenerated.

Related errors

• failed to get PrivKey
• private key in config does not match id: %s != %s
• invalid configuration profile: %s
• unrecognized key type: %s
• cannot add default bootstrap peers: AutoConf is disabled (Au

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