hashicorp/nomad · error

root key not found

Error message

root key not found

What it means

The keyring Delete RPC removes a root key used for variables encryption. If the state store has no root key with the requested KeyID, the endpoint returns this error instead of proceeding to the raft apply.

Source

Thrown at nomad/keyring_endpoint.go:351

	if args.KeyID == "" {
		return fmt.Errorf("root key ID is required")
	}

	// lookup any existing key and validate the delete
	var index uint64
	snap, err := k.srv.fsm.State().Snapshot()
	if err != nil {
		return err
	}
	ws := memdb.NewWatchSet()
	rootKey, err := snap.RootKeyByID(ws, args.KeyID)
	if err != nil {
		return err
	}

	if rootKey == nil {
		return errors.New("root key not found")
	}

	if rootKey != nil && rootKey.IsActive() {
		return fmt.Errorf("active root key cannot be deleted - call rotate first")
	}

	// make sure the key was used to encrypt an existing variable
	rootKeyInUse, err := snap.IsRootKeyInUse(args.KeyID)
	if err != nil {
		return err
	}
	if rootKeyInUse && !args.Force {
		return errors.New("root key in use, cannot delete")
	}

	_, index, err = k.srv.raftApply(structs.WrappedRootKeysDeleteRequestType, args)
	if err != nil {
		return err

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Run `nomad keyring list` and copy the exact key ID.
2. Retry with the correct, existing key ID.
3. If the key was already deleted, treat the operation as complete.

Example fix

// before
nomad keyring remove -key-id 8f2b...wrong

// after
nomad keyring list
nomad keyring remove -key-id <id-from-list>

// verify existence first
keys, err := client.Keyring().List(nil)
// then confirm args.KeyID appears in keys before calling Delete

if _, err := k.Delete(args); err != nil && strings.Contains(err.Error(), "root key not found") {
  // treat as already-deleted; re-list keys to confirm
  return handleAlreadyDeleted(args.KeyID)
}

When it happens

Trigger: Calling the root key delete API/CLI (`nomad keyring remove -key-id <id>`) with a key ID that does not exist in the state store (already deleted, typo'd, or from another cluster).

Common situations: Deleting a key twice in parallel; typing the key ID by hand; targeting the wrong cluster/namespace via environment config.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• variable not found
• root key in use, cannot delete
• variable doesn't exist
• variable error: encrypt: %w
• LockNoPathErr

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/38c1cf135e23641e. Report an issue: GitHub.