ipfs/kubo · error

keystore name for backing up old key must be provided

Error message

keystore name for backing up old key must be provided

What it means

The `ipfs key rotate` command requires the `--old-key` option naming the keystore entry under which the node's current `self` identity key will be backed up before generating a new identity. This error is returned from the command's Run function when the option was not supplied at all (the type assertion to string fails). The rotate operation refuses to destroy the old identity without a safe backup location.

Source

Thrown at core/commands/keystore.go:762

    export IPFS_PATH=/path/to/ipfsrepo
`,
	},
	Arguments: []cmds.Argument{},
	Options: []cmds.Option{
		cmds.StringOption(oldKeyOptionName, "o", "Keystore name to use for backing up your existing identity"),
		cmds.StringOption(keyStoreTypeOptionName, "t", "type of the key to create: rsa, ed25519, secp256k1").WithDefault(keyStoreAlgorithmDefault),
		cmds.IntOption(keyStoreSizeOptionName, "s", "size of the key to generate"),
	},
	NoRemote: true,
	PreRun:   DaemonNotRunning,
	Run: func(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment) error {
		cctx := env.(*oldcmds.Context)
		nBitsForKeypair, nBitsGiven := req.Options[keyStoreSizeOptionName].(int)
		algorithm, _ := req.Options[keyStoreTypeOptionName].(string)
		oldKey, ok := req.Options[oldKeyOptionName].(string)
		if !ok {
			return fmt.Errorf("keystore name for backing up old key must be provided")
		}
		if oldKey == "self" {
			return fmt.Errorf("keystore name for back up cannot be named 'self'")
		}
		return doRotate(os.Stdout, cctx.ConfigRoot, oldKey, algorithm, nBitsForKeypair, nBitsGiven)
	},
}

func doRotate(out io.Writer, repoRoot string, oldKey string, algorithm string, nBitsForKeypair int, nBitsGiven bool) error {
	// Open repo
	repo, err := fsrepo.Open(repoRoot)
	if err != nil {
		return fmt.Errorf("opening repo (%v)", err)
	}
	defer repo.Close()

	// Read config file from repo
	cfg, err := repo.Config()

View on GitHub (pinned to 329838acdf)

Solutions

1. Re-run the command with `--old-key <name>` (e.g. `ipfs key rotate --old-key=old-self`)
2. Pick a keystore name that is not 'self' and does not collide with an existing key you care about
3. Check `ipfs key list` afterwards to confirm the old identity was backed up under the given name

Example fix

// before
ipfs key rotate -o ed25519
// after
ipfs key rotate -o ed25519 --old-key=old-self

oldKey, ok := req.Options[oldKeyOptionName].(string)
if !ok || oldKey == "" {
    return errors.New("--old-key is required for key rotate")
}

func hasOldKey(opts map[string]interface{}) (string, bool) {
    v, ok := opts[oldKeyOptionName].(string)
    return v, ok && v != ""
}

if err := doRotate(os.Stdout, cfgRoot, oldKey, alg, bits, bitsGiven); err != nil {
    if strings.Contains(err.Error(), "must be provided") {
        // prompt user / default the backup name
    }
}

When it happens

Trigger: Running `ipfs key rotate` without the `--old-key <name>` flag; calling the command programmatically via cmds.Request with the oldKeyOptionName option omitted or set to a non-string value.

Common situations: Users copying an older rotate command invocation that predates the --old-key requirement; scripts or automation that forgot the flag; mistyping the flag name so the option is never set.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• encoding PEM block: %w
• refusing to export key to %s: not a regular file, character
• creating temporary file for %s: %w
• flushing %s: %w
• writing %s: %w

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