Vaults Troubleshooting

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:

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.

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 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
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.
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.

A Project Owner who is only a Workspace Viewer sees nothing, because project roles carry no vault permission. See 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.

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 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

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. 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.

A connection stopped working after a vault change

Check, in order:

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.
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.
The provider-side policy still covers the secret. A secret moved out of the allowed prefix or path can no longer be read.
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.
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.