ipfs/kubo · error

cannot overwrite key with name 'self'

Error message

cannot overwrite key with name 'self'

What it means

CoreAPI Key.Rename refuses to overwrite the reserved key 'self' when renaming with force: overwriting the identity alias would replace what 'self' means for the whole node, so it is disallowed even with --force.

Source

Thrown at core/coreapi/key.go:190

// key was overwritten, or an error.
func (api *KeyAPI) Rename(ctx context.Context, oldName string, newName string, opts ...caopts.KeyRenameOption) (coreiface.Key, bool, error) {
	_, span := tracing.Span(ctx, "CoreAPI.KeyAPI", "Rename", trace.WithAttributes(attribute.String("oldname", oldName), attribute.String("newname", newName)))
	defer span.End()

	options, err := caopts.KeyRenameOptions(opts...)
	if err != nil {
		return nil, false, err
	}
	span.SetAttributes(attribute.Bool("force", options.Force))

	ks := api.repo.Keystore()

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

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

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

	pubKey := oldKey.GetPublic()

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

	// This is important, because future code will delete key `oldName`
	// even if it is the same as newName.
	if newName == oldName {
		k, err := newKey(oldName, pid)

View on GitHub (pinned to 329838acdf)

Solutions

1. Pick a different target name for the rename
2. Remove the colliding regular key explicitly with 'ipfs key rm' first if appropriate

Example fix

// before
api.Key().Rename(ctx, "mykey", "self", caopts.AllowOverwrite(true))
// after
if newName == "self" {
    return errors.New("'self' is reserved for the node identity")
}
api.Key().Rename(ctx, "mykey", newName, caopts.AllowOverwrite(true))

if newName == "self" {
    return errors.New("target name 'self' is reserved for the node identity")
}

func isReservedKeyName(n string) bool { return n == "self" }

ok, overwritten, err := api.Key().Rename(ctx, oldName, newName, opts...)
if err != nil && strings.Contains(err.Error(), "overwrite key with name 'self'") {
    return errReservedTarget // reprompt for a different target name
}

When it happens

Trigger: KeyAPI.Rename(ctx, oldName, "self", opts...) or `ipfs key rename mykey self` (including --force).

Common situations: Users trying to make another key 'primary' by naming it self; scripts constructing target names from user input without filtering reserved words.

Related errors

• cannot create key with name 'self'
• unrecognized key type: %s
• cannot rename key with name 'self'
• refusing to export key to %s: not a regular file, character
• cannot import key with name 'self'

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