vault/website/content/docs/updates/important-changes.mdx

---
layout: docs
page_title: Important changes
description: >-
  Deprecations, important or breaking changes, and remediation recommendations
  for upgrading Vault.

valid_change_types: >-
  - Bug --> must include workaround/recommendation info
  - New default
  - New behavior
  - Breaking --> must include workaround/recommendation info
  - Change in support
---

# Important changes

**Last updated**: 2025-06-30

Always review important or breaking changes and remediation recommendations
before upgrading Vault.

## New behavior

### Key pair authentication for Snowflake DB secrets engine

| Change       | Affected version | Affected deployments
| ------------ | ---------------- | --------------------
| New behavior | 1.20.0           | any

As of version 1.20.0, Vault supports
[Snowflake database authentication using key pairs](/vault/api-docs/secret/databases#configure-connection)
as an alternative to password authentication, which Snowflake plans to disable
in November 2025. Vault support for password authentication with Snowflake is
now deprecated and will be removed in a future release.

Vault currently does not support rotate root for key pairs. To manually rotate key pairs, users can:

  - update the root configuration in Vault with the new private key
  - update the public key associated with the user in Snowflake

For more information on rotating key pairs, please refer
to the official [Snowflake documentation](https://docs.snowflake.com/en/user-guide/key-pair-auth#configuring-key-pair-rotation).

## Breaking changes

### Breaking configuration change for disable_mlock ((#disable_mlock-config))

| Change       | Affected version | Fixed version
| ------------ | ---------------- | --------------------
| Breaking     | 1.20.0           | N/A

In Vault 1.20.0 `disable_mlock` is a required configuration setting for
clusters using *integrated storage*. This means that if you are not explicitly
setting a value for `disable_mlock`, the following changes must be made prior
to upgrading.

<Warning>

Clusters missing this config value will fail to start after the upgrade to 1.20.0.

</Warning>

Before upgrading to Vault 1.20.0, administrators must explicitly add a value for
`disable_mlock` to the outermost level of the server configuration. Refer to the [documentation](/vault/docs/configuration#parameters).
This must be done for all server nodes. Prior to Vault 1.20, the default setting
for `disable_mlock` was false. Therefore, if you do not currently have a value
set for `disable_mlock`, you are using the default setting. If you wish to
maintain this behavior, you will need to explicitly set
`disable_mlock = false` prior to upgrade.

For clusters that already set a value for `disable_mlock`, no change is required.

| Cluster Type               | `disable_mlock` required | Note
|----------------------------|--------------------------|-----
| Primary                    | Yes                      | value depends on cluster specifics. [See docs](/vault/docs/configuration#disable_mlock)
| Performance Secondary      | Yes                      | value depends on cluster specifics. [See docs](/vault/docs/configuration#disable_mlock)
| DR Secondary               | Yes                      | value depends on cluster specifics. [See docs](/vault/docs/configuration#disable_mlock)


### One of bound_group_ids or bound_service_principal_ids Must Be Specified in the Role Definition for Azure Authentication Roles

Azure authentication roles must specify either `bound_group_ids` or `bound_service_principal_ids` in the role definition to prevent
excessively permissive access. This ensures that the role is tailored to the specific needs of the application or service. More information about Azure
authentication roles can be found [here](/vault/docs/auth/azure). Here's an updated example for reference:

```shell-session
$ vault write auth/azure/role/dev-role \
    policies="prod,dev" \
    bound_subscription_ids=6a1d5988-5917-4221-b224-904cd7e24a25 \
    bound_resource_groups=vault \
    bound_service_principal_ids=3cb88732-1356-4782-b671-4877166be01a
```

### Audiences Will Be Required for Kubernetes Authentication Roles in Vault 1.21+

Starting in Vault 1.21+, specifying an **audience** will be **mandatory** for all Kubernetes authentication roles. This ensures that the JWT token's aud (audience) claim is explicitly validated, confirming that the token is intended for Vault and not another service.

Currently, creating or updating a Kubernetes auth role without an audience will result in a warning. However, once Vault 1.21 is released, **any role that does not specify an audience will fail authentication.**

To prepare for this change, make sure to include the audience parameter when defining Kubernetes auth roles. More information about Kubernetes authentication roles can be found [here](/vault/docs/auth/kubernetes). Here's an updated example:

```shell-session
vault write auth/kubernetes/role/demo \
    bound_service_account_names=myapp \
    bound_service_account_namespaces=default \
    policies=default \
    ttl=1h
```

#### Additional Considerations

- **Autopilot** - New 1.20.0 nodes are added to the cluster until there is a
  quorum of upgraded nodes. Each of these new nodes will need to have a value
  for `disable_mlock` set.

- **Rolling upgrades** - Standby nodes are stopped and upgraded one at a time.
  These node configurations will need to be updated before restarting the vault
  process on the node.

- **`dev` mode** - If no config is provided, dev mode will start as usual. If a
  config is provided, it must have a value for `disable_mlock`.


### Rekey cancellations use a nonce ((#rekey-cancel-nonce))

| Change       | Affected version                          | Fixed version
| ------------ | ----------------------------------------- | --------------------
| Breaking     | 1.20.0, 1.19.6, 1.18.11, 1.17.18, 1.16.21 | N/A

Vault 1.20.0, 1.19.6, 1.18.11, 1.17.18, and 1.16.21 require a nonce to cancel
[rekey](/vault/api-docs/system/rekey) and
[rekey recovery key](/vault/api-docs/system/rekey-recovery-key) operations
within 10 minutes of initializing a rekey request. Cancellation requests after
the 10 minute window do not require a nonce and succeed as expected.

#### Recommendation

To cancel a rekey operation, provide the nonce value from the
`/sys/rekey/init` or `sys/rekey-recovery-key/init` response.


## Bugs

None.


## Known issues

### UI login fails for auth mounts with underscores and unauthenticated listing ((#ui-login-underscore))

| Change       | Affected version | Fixed version
| ------------ | ---------------- | --------------------
| Known issue  | 1.20.0           | 1.20.1

Login requests to auth methods mounted at paths using underscores (e.g. `oidc_test`)
with `listing_visibility="unauth"` fail because the GUI calls the wrong
endpoint. Mounts with dashes (e.g. `oidc-test`) work correctly.

#### Recommendation

As a workaround, you can log in to the GUI using the following steps:

1. Navigate directly to the URL for the desired method type (e.g. `${VAULT_ADDR}/ui/vault/auth?with=oidc`)
1. Click "Sign in with other methods ->"
1. Select the method type from the dropdown
1. Click **Advanced settings** and provide the correct path (e.g., `oidc_test`).

We also recommend creating a [custom GUI message](/vault/docs/ui/custom-message) describing the workaround steps for users.

### Duplicate unseal/seal wrap HSM keys ((#hsm-keys)) <EnterpriseAlert inline="true" />

| Change      | Status | Affected version                       | Fixed version
| ----------- | ------ | -------------------------------------- | --------------------
| Known issue | Open   | 1.20.x, 1.19.x, 1.18.x, 1.17.x, 1.16.x | None

In HSM-HA configurations migrating from Shamir to HSM-backed unseal/seal wraps,
Vault may create duplicate HSM keys when you migrate from Shamir to an
HSM-backed unseal configuration for high availability (HA) HSM deployments. Key
duplication can happen even after a seal migration to HSM that initially
appears successful.

Duplicate HSM keys can cause the following errors:

- intermittent read failures with errors such as `CKR_SIGNATURE_INVALID` and `CKR_KEY_HANDLE_INVALID` for
[seal-wrapped values](/vault/docs/enterprise/sealwrap#wrapped-parameters).
- nodes fail to unseal after a restart with errors such as `CKR_DATA_INVALID`.

#### Recommendation

Always run Vault with `generate_key = false` and manually create all required
keys within the HSM during the setup process.

### Duplicate LDAP Password Rotations on Standby Node Check-In ((#ldap-checkin))

| Change       | Affected version                          | Fixed version
| ------------ | ----------------------------------------- | --------------------
| Known issue  | 1.12.0+                                   | N/A

Vault check-ins for LDAP service accounts performed on a performance standby node or a node in a
performance replication secondary cluster can trigger duplicate password changes on the LDAP server.
Duplication occurs because the LDAP client on the local node successfully modifies the password before Vault
forwards the check-in request to the active node, which then performs a second password update.
While users still receive the latest password, it may lead to unexpected LDAP activity and cause
confusion interpreting audit logs.

### Recommendation:

Send check-in requests directly to the active node of the primary cluster to prevent duplicate password
rotations on the LDAP server.

### Development cluster setting overwritten on secondary cluster reload ((#development-cluster-reload))

| Change       | Affected version | Fixed version
| ------------ |------------------| --------------------
| Known issue  | 1.20.0           | N/A

If the Vault process receives a `SIGHUP` and reloads a secondary performance
replication cluster, the cluster reverts to the locally configured
`development_cluster` value instead of following the value configured on the
primary cluster.

#### Recommendation:

Ensure all clusters in a performance replication group have the same `development_cluster` value configured in HCL to
prevent unexpected changes to the reported value.