hashicorp/nomad · warning

keyring is not ready - waiting for keys %s

Error message

keyring is not ready - waiting for keys %s

What it means

The keyring does not yet contain all keys referenced by keyring metadata (currentPendingTasks is non-empty), so encryption/signing work is temporarily refused. This is an expected transient condition while remote/KMS-wrapped keys are still being decrypted after startup or rotation.

Source

Thrown at nomad/encrypter.go:257

		for _, id := range basePendingTasks {
			if _, ok := e.decryptTasks[id]; ok {
				currentPendingTasks = append(currentPendingTasks, id)
			}
		}

		// If we have decryption tasks which are still running that we care
		// about, log about this as well as return an error. If key decryption
		// progresses over time, an operator will be able to identify any
		// long-running tasks. If the timeout is reached, the final error is
		// sent to the caller which identifies the tasks that are taking too
		// long.
		if l := len(currentPendingTasks); l > 0 {

			e.log.Debug("waiting for keyring to be ready",
				"num_tasks", l, "key_ids", currentPendingTasks)

			return fmt.Errorf("keyring is not ready - waiting for keys %s",
				strings.Join(currentPendingTasks, ", "))
		}
		return nil
	})
	if err != nil {
		return err
	}
	return nil
}

// Encrypt encrypts the clear data with the cipher for the active root key, and
// returns the cipher text (including the nonce), and the key ID used to encrypt
// it
func (e *Encrypter) Encrypt(cleartext []byte) ([]byte, string, error) {
	cs, err := e.activeCipherSet()
	if err != nil {
		return nil, "", err
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Wait and retry — the operation is retried with backoff and should succeed once keys unwrap
2. Check server logs for decrypt task errors for the listed key IDs (KMS auth failures, network to KMS endpoint)
3. Verify the KEK provider configuration (credentials, region, Vault token) for the listed keys
4. If a key can never be unwrapped (lost KMS key), restore it from backup or rotate away from it

Example fix

// before: KMS creds absent, key never unwraps, calls keep failing
// after: supply the provider credentials so unwrap completes
//   export AWS_REGION=us-east-1
//   export AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=...
// then restart nomad agent and let pending key tasks drain

// poll keyring readiness before dependent work
func waitForKeys(cli *api.Client, timeout time.Duration) error {
  deadline := time.Now().Add(timeout)
  for time.Now().Before(deadline) {
    if _, _, err := cli.Keyring().List(nil); err == nil { return nil }
    time.Sleep(2 * time.Second)
  }
  return fmt.Errorf("keyring not ready after %s", timeout)
}

// the server itself retries; callers should tolerate transient failure
err := retry.Do(func() error {
  _, err := vars.Decrypt(ctx, blob)
  if strings.Contains(err.Error(), "keyring is not ready") {
    return retry.Delay(2*time.Second) // transient, retry
  }
  return retry.Unrecoverable(err)
});

When it happens

Trigger: keyringIsReady (called before variable encryption or claim signing) finds pending decrypt tasks — keys listed in keystore metadata whose wrapped key material has not yet been resolved via configured KMS providers.

Common situations: Server just started and is still unwrapping keys via slow cloud KMS (AWS KMS, Vault transit), KMS provider credentials missing so unwrap retries indefinitely, or a key was added on the leader while this server is still catching up.

Related errors

• unable to decrypt wrapped key
• %w (root key): %w
• no such provider %q configured
• retry config is nil or empty
• root key not found

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