What causes "cannot remove key with name 'self'" in ipfs/kubo?

Skip the 'self' key when deleting keys programmatically (filter it out of the list).

cannot remove key with name 'self'

Error message

cannot remove key with name 'self'

What it means

The KeyAPI.Remove call refuses to delete the 'self' key, which holds the node's identity private key. The 'self' key is fundamental to the node's peer identity, libp2p identity, and IPNS publishing, so removing it would corrupt the node. The API deliberately blocks it with this sentinel error.

Source

Thrown at core/coreapi/key.go:250

	err = ks.Delete(oldName)
	if err != nil {
		return nil, false, err
	}

	k, err := newKey(newName, pid)
	return k, overwrite, err
}

// Remove removes keys from keystore. Returns ipns path of the removed key.
func (api *KeyAPI) Remove(ctx context.Context, name string) (coreiface.Key, error) {
	_, span := tracing.Span(ctx, "CoreAPI.KeyAPI", "Remove", trace.WithAttributes(attribute.String("name", name)))
	defer span.End()

	ks := api.repo.Keystore()

	if name == "self" {
		return nil, errors.New("cannot remove key with name 'self'")
	}

	removed, err := ks.Get(name)
	if err != nil {
		return nil, fmt.Errorf("no key named %s was found", name)
	}

	pubKey := removed.GetPublic()

	pid, err := peer.IDFromPublicKey(pubKey)
	if err != nil {
		return nil, err
	}

	err = ks.Delete(name)
	if err != nil {
		return nil, err
	}

View on GitHub (pinned to 329838acdf)

Solutions

Skip the 'self' key when deleting keys programmatically (filter it out of the list).
To change the node identity, generate a new one by removing the PeerID/private key from the repo (or re-init the repo), not by calling key rm.
If you truly need a disposable identity, create a separate key with `ipfs key gen` instead.

Example fix

// before
for _, k := range keys { api.Key().Remove(ctx, k.Name) }
// after
for _, k := range keys {
    if k.Name != "self" {
        api.Key().Remove(ctx, k.Name)
    }
}

Defensive patterns

Strategy: validation

Validate before calling

if name == "self" {
    return fmt.Errorf("refusing to remove the 'self' identity key")
}
err := api.Key().Remove(ctx, name)

Prevention

Never include "self" in programmatic key-deletion lists.
Treat the 'self' key as immutable infrastructure, not user data.
Rotate identity by re-initializing the repo, not by deleting keys.

When it happens

Trigger: Calling KeyAPI.Remove(ctx, "self"), e.g. via `ipfs key rm self`.

Common situations: Scripts that iterate over `ipfs key list` output and delete every listed key; users who want to rotate their node identity and try deleting 'self' first.

Related errors

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