# Vaults Troubleshooting > Part of the NocoDB documentation (Product docs > Integrations > Vaults ☁). Index of all pages: https://nocodb.com/llms.txt. Any docs page is available as Markdown by adding `.md` to its URL. URL: https://nocodb.com/docs/product/integrations/vaults/troubleshooting Last updated: 2026-11-11 What NocoDB Enterprise Vaults error messages mean and how to fix them: failed vault tests, references that fail at connection time or on save, and refused name, scope and disconnect changes. This page lists the NocoDB Enterprise Vaults messages that are not specific to one provider. Each provider page ends with a **Common errors** table for its own messages: * [HashiCorp Vault](/docs/product/integrations/vaults/hashicorp-vault#common-errors) * [AWS Secrets Manager](/docs/product/integrations/vaults/aws-secrets-manager#common-errors) * [Azure Key Vault](/docs/product/integrations/vaults/azure-key-vault#common-errors) * [Google Secret Manager](/docs/product/integrations/vaults/google-secret-manager#common-errors) * [CyberArk Conjur](/docs/product/integrations/vaults/cyberark-conjur#common-errors) ## The vault's test fails A vault test that fails shows a NocoDB message naming the likely cause. Three messages are shared by HashiCorp Vault and Conjur, the two providers you host yourself: | Message | Cause | Fix | | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | The vault address (Conjur: appliance URL) resolves to a private or link-local network, which NocoDB Cloud cannot reach. Use an address NocoDB Cloud can reach. | On NocoDB Cloud: the provider is on a private address | Expose the provider on a public address and allow NocoDB Cloud through the firewall | | The vault address (Conjur: appliance URL) resolves to a private or link-local network. To allow it, set NC\_ALLOW\_LOCAL\_VAULTS=true on the NocoDB server. | On self-hosted NocoDB: private addresses are blocked by default | Set `NC_ALLOW_LOCAL_VAULTS=true` on the NocoDB server and restart it | | The … server's TLS certificate is not trusted. | A private CA | Add it with `NODE_EXTRA_CA_CERTS` on the NocoDB server; on Cloud, use a public CA | Two generic messages can come from any provider: | Message | What it means | | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | Could not reach the vault. Check the vault configuration and try again. | The test failed in a way NocoDB could not classify. The raw error is in the server log | | Could not build the vault connection. Check the vault configuration and try again. | The stored configuration could not be turned into a provider client. Update the vault's credentials | NocoDB never shows the provider's raw error, not even to the person running the test, because it can contain ARNs and account ids. Each message is NocoDB's own. The stored result records only whether the test passed and when, and no message, since everyone who can list vaults can see it. Self-hosted administrators can find the raw error in the server logs. ## A reference fails when the connection runs A vault reference is resolved when the connection opens. These messages appear then, for example on **Test connection** or when a project loads data. | Message | What it means | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | The referenced secret holds a JSON document. The reference must name a field inside it. (vault 'x') | The secret is a key/value secret with several fields and the reference points at the whole document. Reselect the reference and name the field, for example `password` | | The referenced secret holds a plain string, so the reference must not name a field inside it. (vault 'x') | The opposite: a single-value secret with a field name attached, usually a plain-text AWS secret. (The form drops a field on Azure, Google and Conjur references; through the API one is accepted only when the secret's value is JSON text.) Clear the field | | The referenced secret has no field 'y'. (vault 'x') | The field name does not exist in the secret. Check the spelling against the secret in your secrets manager | | Field 'y' of the referenced secret is not a single value. (vault 'x') | The field holds a nested object or a list. A credential field needs a scalar | | No such secret in this region… / Vault denied access to this secret… / No such variable in this account… | A read failed at the provider. Find the message in that provider's **Common errors** table | | A referenced secret could not be read. | A read failed in a way NocoDB could not classify. The raw error is in the server log | | No vault named 'x' is connected to this workspace. | The reference names a vault that is not connected here, was disconnected, or was moved to another workspace | | This vault is not configured. Reconnect it before using its secrets. | The vault exists but has no usable credentials. Update its credentials and test it | NocoAI and AI agents show these messages too, instead of a generic failure to start, so the person can tell a missing secret or a disconnected vault from a provider outage. These messages name the vault and the field, but never the secret's own identifier. An AWS ARN contains the account id, and the person who hits one of these errors at connection time is often not the person who wrote the reference. The full identifier is written to the server log instead, so an operator can match the two up. See [Naming a field inside the secret](/docs/product/integrations/vaults/use-a-vault-reference#naming-a-field-inside-the-secret). ## A reference is rejected when I save the connection NocoDB checks every vault reference when a connection is saved. These messages appear then. | Message | What it means | | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | You are not allowed to use the vault 'x'. Ask a workspace owner to grant you access to it, or enter the credential directly. | You can see the vault but its [Who can use this vault](/docs/product/integrations/vaults#who-can-use-a-vault) setting does not include you. A Workspace Owner sees this for a vault set to **Inactive**, or to specific people they are not among, and for an organization vault left at **Org owners and admins**. For an organization vault the message says "Ask an organization owner or admin" instead. Ask whoever manages the vault to change the setting | | This integration uses a vault secret, which editors can't use. Ask a workspace creator or owner. | An **Editor** ran a script that uses an integration holding a reference to a vault whose setting does not include them. Have a Workspace Creator or Owner who may use the vault run it. See [In a script](/docs/product/integrations/vaults/use-a-vault-reference#in-a-script) | | No vault named 'x' is available to you. Reference one of the vaults connected to this workspace or its organization. | The vault does not exist, or you are below Owner and not allowed to use it. The message is the same either way | | Vault references are not supported on this integration. Enter the credential directly. | A reference was used on an integration with no vault-capable field: an OAuth sign-in, or a sync, channel or action integration. Only database, AI and authentication integrations resolve references | | A vault reference is not allowed at 'x'. Only the credential fields of this integration can be vault-backed. | A reference was placed on a field that is not a credential (a host, an organization id, a model list), on an integration or on a data source added to a project. Move it to the field the form marks with **Use a vault** | | 'x' is not a valid secret reference. It needs a vault name and a secret id, and any field path must be a list of non-empty strings. | A reference sent through the API is malformed | | A workspace is required to test a connection that references a vault. | **Test connection** was run on an unsaved form outside a workspace. Open the form from the workspace **Integrations** page | ## I cannot see the Vaults option at all Three independent things decide whether NocoDB shows vaults, and they do not interact. * **Plan.** Vaults are hidden on the Free plan and on self-hosted NocoDB without a license. Every paid plan shows them, but without the **Enterprise Vaults** add-on they carry an **Add-on** badge and nothing can be connected or referenced. The add-on needs the **Enterprise** plan, on NocoDB Cloud, or a **Self-hosted Enterprise** license. See [Turning on Enterprise Vaults](/docs/product/integrations/vaults#turning-on-enterprise-vaults). * **Role.** Connecting, editing, testing and disconnecting a workspace vault, and the banner on the Integrations page, need **Workspace Owner**. Every organization-vault operation, the list included, needs **Org Admin**. * **Who can use the vault.** The **Use a vault** option on a connection appears only when at least one vault lets you use it. Each vault's owner decides that. The default is Workspace Owners for a workspace vault, and the organization's owners and admins for an organization vault. See [Who can use a vault](/docs/product/integrations/vaults#who-can-use-a-vault). A Project Owner who is only a Workspace Viewer sees nothing, because project roles carry no vault permission. See [Permissions](/docs/product/integrations/vaults#permissions). ## Connect a vault opens "Available as an Enterprise add-on" The workspace or organization is on a paid plan without the **Enterprise Vaults** add-on. **Connect a vault** on the Integrations banner or in the Admin Panel, and **Use a vault** under a credential field, open this dialog instead of the vault wizard. Click **Contact Sales** to have the add-on enabled. See [Turning on Enterprise Vaults](/docs/product/integrations/vaults#turning-on-enterprise-vaults). Through the API, and when a connection that holds a reference opens, the same check fails with one of these messages: | Message | What it means | | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Enterprise Vaults require the Enterprise Vaults add-on. Contact sales to add it to your plan. | NocoDB Cloud: the workspace, or its organization, does not have the add-on. That includes an Enterprise plan, which does not include vaults on its own. Contact the [sales team](https://cal.com/nocodb/sales) to have it added | | Enterprise Vaults require the Enterprise Vaults add-on. Contact sales to add it to your license. | Self-hosted: the license key does not include the add-on. After NocoDB adds it, [activate the updated license](/docs/self-hosting/license-activation) | Connections that reference a vault stop resolving while the add-on is missing, and the credential field shows "The Enterprise Vaults add-on is not active, so this reference will not resolve. Enter the value directly instead." Owners cannot list, edit or disconnect the stored vaults until the add-on is back. A data source whose credentials come from a vault is closed and fails to open until the add-on is back or the credential is entered directly. ## I cannot see the credentials I entered A NocoDB vault's own credentials are write-only, for everyone including the Workspace Owner who entered them. No endpoint returns them, so there is no path to read them back. To change them, enter the new values in full. Likewise, no role can read the value of a secret through NocoDB. Secret names and the field names inside a secret are offered as suggestions only to people allowed to use that vault, never the values. ## The reference name is refused A vault's reference name must follow the [reference name rules](/docs/product/integrations/vaults#choosing-the-reference-name). These messages appear when you connect a vault: | Message | What it means | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | A vault name can be at most 64 characters. | Shorten the name | | 'x' cannot be used as a vault name. It is the name every reference uses, so it must start with a letter and contain only letters and digits, and must not be one of the reserved names (…). | The name has a space, dash or underscore, starts with a digit, or is reserved | | A vault named 'x' is already connected to this workspace. | Pick a different name. Names are compared without regard to case | | A vault named 'x' is already connected to this organization. A vault name must be unique across the organization and its workspaces, because it is what every reference names. | An organization vault already uses the name | | A vault named 'x' is already connected to a workspace in this organization. A vault name must be unique across the organization and its workspaces. | You are connecting an organization vault and a workspace already uses the name | | A vault named 'x' was connected at the same moment by someone else. Nothing was saved — pick a different name, or use the vault that now exists. | Two people connected a vault with the same name at once | Two sibling workspaces may each connect a vault with the same name. The clash then surfaces only when one of them is made organization-wide. See the next section. ## A scope change is refused | Message | What it means | | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | This organization already has a vault named 'x'. Rename or disconnect one of them before making this one organization-wide. | Making a workspace vault organization-wide would clash with an organization vault of the same name | | Another workspace in this organization already has a vault named 'x'. Rename or disconnect it before making this one organization-wide. | The same clash, with another workspace's vault | | That workspace already has a vault named 'x'. Rename or disconnect it before moving this one there. | The target workspace has its own vault with that name | | N integrations in other workspaces still reference 'x'. Replace those references before limiting this vault to one workspace. | Limiting the vault to one workspace would break connections elsewhere. Repoint those connections, then try again | | A workspace must be named to move this vault out of organization scope. | Through the API: the request did not name the target workspace | Making a vault organization-wide resets who can use it to **Org owners and admins**. Workspace owners lose access unless you then pick **Workspace owners** or add them under **Specific people**. ## Moving a workspace into an organization is refused Moving a workspace into an organization, or from one organization to another, is refused when it would cost the workspace an add-on or break its vault references: | Message | What it means | | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | This workspace has add-ons the organization's subscription does not include (…). Add them to the organization before moving the workspace. | The workspace has its own **Enterprise Vaults** add-on and the target organization does not. Moving would remove it and stop every reference resolving | | This workspace has a vault named 'x', and the organization already has one with that name. Rename or disconnect one of them before moving the workspace. | Reference names must be unique across an organization and its workspaces | | N integrations in this workspace reference the current organization's vault 'x'. Replace those references before moving the workspace. | Those references would stop resolving once the workspace leaves the organization | ## I need to rename a vault's reference name A NocoDB vault's reference name cannot be changed. Every stored reference embeds the name and nothing rewrites them. Through the API, a rename is refused with "A vault's name cannot be changed — every stored reference names 'x', and nothing rewrites them. Connect a new vault and repoint the references instead." To change it, connect a second vault under the new name, repoint the connections that use the old one, and then disconnect the old vault. ## A vault cannot be disconnected NocoDB refuses to disconnect a vault that integrations still reference: > This vault is still used by 3 integrations. Replace the secret references before disconnecting it. The count covers database connections, AI and authentication integrations, data source settings and per-environment overrides. Repoint or delete those integrations, then disconnect the vault. See [Disconnecting a vault](/docs/product/integrations/vaults#disconnecting-a-vault). ## A connection stopped working after a vault change Check, in order: 1. The vault's credentials still work. The Org Admin can run **Test connection** on the vault's row under **Vaults** in the Admin Panel. Rotating the credential in your secrets manager without updating the vault breaks every connection that references it. 2. The secret still exists under the same id, and still has the field the reference names. Renaming a secret or a field in your secrets manager breaks the reference. 3. The provider-side policy still covers the secret. A secret moved out of the allowed prefix or path can no longer be read. 4. The vault still exists in NocoDB. NocoDB refuses to disconnect a vault that connections still reference, but it cannot stop you deleting the secret itself. 5. The workspace still has the **Enterprise Vaults** add-on. References stop resolving when the add-on is removed, and moving a workspace below Enterprise removes it. ## Related * [Enterprise Vaults overview](/docs/product/integrations/vaults) * [Use a vault reference](/docs/product/integrations/vaults/use-a-vault-reference) --- ## Related pages - [Connect AWS Secrets Manager](https://nocodb.com/docs/product/integrations/vaults/aws-secrets-manager.md): Connect AWS Secrets Manager to NocoDB as an Enterprise vault: create an IAM policy, an IAM user and an access key, then reference secrets from your integrations. - [Connect HashiCorp Vault](https://nocodb.com/docs/product/integrations/vaults/hashicorp-vault.md): Connect HashiCorp Vault to NocoDB as an Enterprise vault: write a policy, create an AppRole, then read secrets from a KV v2 mount in your integrations. - [Connect Azure Key Vault](https://nocodb.com/docs/product/integrations/vaults/azure-key-vault.md): Connect Azure Key Vault to NocoDB as an Enterprise vault: register an Entra ID application, give it read access to the Key Vault, then reference secrets from your integrations. - [Connect Google Secret Manager](https://nocodb.com/docs/product/integrations/vaults/google-secret-manager.md): Connect Google Secret Manager to NocoDB as an Enterprise vault: create a service account with secret access, add its key, then reference secrets from your integrations. - [Connect CyberArk Conjur](https://nocodb.com/docs/product/integrations/vaults/cyberark-conjur.md): Connect CyberArk Conjur to NocoDB as an Enterprise vault: load a policy with a host and variables, then reference the variables from your integrations with the host API key. - [Use a Vault Reference](https://nocodb.com/docs/product/integrations/vaults/use-a-vault-reference.md): Point a credential on a NocoDB database connection, AI provider or authentication integration at a secret in a connected Enterprise vault instead of typing the value.