ipfs/kubo · error

'%q' is not a known key, an IPNS Name, or a valid PeerID

Error message

'%q' is not a known key, an IPNS Name, or a valid PeerID

What it means

KeyAPI.Verify accepts either a key name, an IPNS name, or a PeerID. When the provided string is none of these, the lookup path falls through to this error. The keystore was checked, the IPNS-name parse/ExtractPublicKey path was exhausted, and the string did not resolve to any usable public key.

Source

Thrown at core/coreapi/key.go:338

		name string
		pk   crypto.PubKey
		err  error
	)
	if keyOrName == "" || keyOrName == "self" {
		name = "self"
		pk = api.privateKey.GetPublic()
	} else if sk, err := api.repo.Keystore().Get(keyOrName); err == nil {
		name = keyOrName
		pk = sk.GetPublic()
	} else if ipnsName, err := ipns.NameFromString(keyOrName); err == nil {
		// This works for both IPNS names and Peer IDs.
		name = ""
		pk, err = ipnsName.Peer().ExtractPublicKey()
		if err != nil {
			return nil, false, err
		}
	} else {
		return nil, false, fmt.Errorf("'%q' is not a known key, an IPNS Name, or a valid PeerID", keyOrName)
	}

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

	key, err := newKey(name, pid)
	if err != nil {
		return nil, false, err
	}

	data = append([]byte(signedMessagePrefix), data...)

	valid, err := pk.Verify(data, signature)
	if err != nil {
		return nil, false, err
	}

View on GitHub (pinned to 329838acdf)

Solutions

1. Pass a key name that exists in the local keystore (`ipfs key list`).
2. Pass a valid PeerID (multibase/multihash identity of a public key) or a valid IPNS name.
3. Strip prefixes like /ipns/ or /p2p/ before passing the identifier.
4. If verifying with a raw public key not in the keystore, embed it in a PeerID that carries the pubkey (identity multihash) or import the key first.

Example fix

// before
pk, err := api.Key().Verify(ctx, "/ipns/k51qzi5uqu5d...", msg, sig)
// after
pk, err := api.Key().Verify(ctx, "k51qzi5uqu5d...", msg, sig)

func isVerifiableID(s string) bool {
    if _, err := peer.Decode(s); err == nil {
        return true
    }
    if strings.HasPrefix(s, "/ipns/") {
        return true
    }
    return false // otherwise require it to be a keystore key name
}

func isPeerIDString(s string) bool {
    _, err := peer.Decode(s)
    return err == nil
}

pk, err := api.Key().Verify(ctx, keyOrName, msg, sig)
if err != nil && strings.Contains(err.Error(), "is not a known key") {
    return fmt.Errorf("invalid verification identity %q: use a keystore key name, IPNS name, or PeerID", keyOrName)
}

When it happens

Trigger: Calling KeyAPI.Verify(ctx, keyOrName, msg, sig) with an arbitrary string that is not a keystore key name, not parseable as an IPNS name, and not a valid PeerID.

Common situations: Passing a full /ipns/ or /p2p/ multiaddr-style string instead of the bare ID; passing a CID that is not a peer ID; passing a key name from a different node's keystore.

Related errors

• Name.Resolve: depth other than 1 or %d not supported
• cannot import key with name 'self'
• DHT timeout value must be >= 0
• can't put while offline: pass `--allow-offline` to store loc
• cannot use both --allow-offline and --allow-delegated flags

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