hashicorp/nomad · critical

could not add key file %s to keystore: %w

Error message

could not add key file %s to keystore: %w

What it means

addCipher rejected the root key after it was loaded from the key file. addCipher builds the cipher set (AEAD wrapper, ed25519/rsa signing keys); errors here mean the key material is structurally invalid (e.g. missing or malformed signing keys) and cannot be registered in the keyring.

Source

Thrown at nomad/encrypter.go:195

		e.keyringLock.RLock()
		_, ok := e.keyring[id]
		e.keyringLock.RUnlock()
		if ok {
			return nil // already loaded this key from another file
		}

		key, err := e.loadKeyFromStore(path)
		if err != nil {
			keyErrors[id] = fmt.Errorf("could not load key file %s from keystore: %w", path, err)
			return nil
		}
		if key.Meta.KeyID != id {
			return fmt.Errorf("root key ID %s must match key file %s", key.Meta.KeyID, path)
		}

		err = e.addCipher(key)
		if err != nil {
			return fmt.Errorf("could not add key file %s to keystore: %w", path, err)
		}

		// we loaded this key from at least one KEK configuration, so clear any
		// error from a previous file that we couldn't read from
		delete(keyErrors, id)
		return nil
	})

	if len(keyErrors) == 0 {
		return nil
	}

	var mErr multierror.Error
	for _, err := range keyErrors {
		mErr = *multierror.Append(&mErr, err)
	}
	return mErr.ErrorOrNil()
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped cause to see which part of addCipher failed (wrapper setup vs signing keys)
2. Verify all servers run compatible Nomad versions (same key algorithm support)
3. Restore the key file from a backup or another server's keystore
4. Rotate to a new key with nomad keyring rotate and remove the unusable key once no data is encrypted under it

Example fix

// before: mixed cluster versions produce unsupported key algorithm
//   servers at 1.5.x cannot addCipher keys minted by 1.7.x
// after: upgrade all servers to the same version, then restart
$ nomad version && nomad server members  # confirm uniform versions

// confirm uniform Nomad versions across servers before rotations
$ for s in $(nomad server members -format json | jq -r '.[].Name'); do nomad node status -verbose $s | grep Version; done

When it happens

Trigger: loadKeystore successfully loads and ID-verifies a key, then calls e.addCipher(key); addCipher returns an error when the key's algorithm is unknown or the embedded public/private key material cannot be reconstructed.

Common situations: Key file produced by a newer/older Nomad version with an unsupported algorithm field, hand-edited key JSON, or partially written file from a crash.

Related errors

• root key ID %s must match key file %s
• Failed to query for root keys: %v
• could not load key file %s from keystore: %w
• invalid signature: %w
• failed to fetch key from any peer: %v

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