HashiCorp Vault Troubleshooting

This page documents the connection-test failures a connection with Secrets Management can produce and how to resolve them. The steps happen in a fixed order, reaching Vault, logging in, fetching the secret, and using it, so the sections below follow that order. Each message appears in the Connection test failed banner; match the wording.

Reaching Vault

The Test Waits About Two Minutes and Fails with a Gateway Timeout

The banner reads Request took longer than expected. Please retry. (Status: 504).

Cause: The whole request timed out. A connection test reaches Vault, reads the secret, and then connects to the data source, and the message only says that the sum of those took too long. The most common stall is Vault itself: no network path from the Qualytics addresses to Vault's host and port, or a Vault hostname that does not resolve from inside the Qualytics deployment. A data source that is slow to answer can produce the same message after Vault succeeded.

Resolution: Find the stage that stalled before changing anything. If the same connector works when Secrets Management is turned off and the credentials are typed in, Vault is the stall; if it times out either way, the data source is. For a Vault stall, allow the addresses shown below the connection form through the firewall to Vault's host and port and use a hostname that resolves from inside the deployment; see Network Requirements. The Secrets Management field values are not evaluated until Vault answers, so retrying the form with different values does not help until the path exists.

The Test Fails Immediately with an Unreachable Message

The banner reads Unable to establish connection to the configured secrets manager or Unable to reach the configured secrets manager at [...].

Cause: The connection was refused, the hostname could not be resolved, or the TLS handshake failed.

Resolution: Check the host and port in both URLs, and that Vault's certificate chain is trusted by your Qualytics deployment. After fixing the cause, wait for the retry named in the message, up to five minutes after the failure, before testing again. Until then the test fails right away without contacting Vault, which is not a sign that the fix did not work.

The Test Fails with a Bad Gateway Message

The banner reads Bad gateway. The server received an invalid response. (Status: 502).

Cause: An unexpected failure while talking to Vault. The most common reason is a Login URL or Secret URL that is not a complete URL, for example a bare path with no https:// and host.

Resolution: Make both URLs complete, then test again.

Logging In

Invalid Role or Secret ID

The banner reads The secrets manager login attempt failed. It responded with: [400: Bad Request - ['invalid role or secret ID']].

Cause: Either the role does not exist at the path the Login URL points to, or the secret ID is no longer valid. The first is far more common with namespaces: the AppRole lives inside a namespace, but the Login URL points at the root namespace. Vault reports an unknown role as invalid credentials by design. The second happens when the secret ID expired or ran out of uses.

Resolution: Confirm which namespace the AppRole is enabled in and add it after /v1/ in the Login URL; see Namespaces. If the namespace is already right, mint a new secret ID and update the Credentials Payload, as in Prepare Vault.

The banner reads The secrets manager login attempt failed because the configured service [...] was not found: [404].

Cause: The Login URL path is wrong. Usually the auth method is mounted under a name other than approle, or the namespace is missing or misspelled.

Resolution: Open Access in the Vault UI, with the namespace selector set correctly, and copy the mount path shown there into the Login URL.

The banner reads The path [$.auth.client_token] was not available in the secrets manager's login response.

Cause: The login endpoint answered, but not in Vault's shape. This happens with a secrets manager other than Vault, or with a proxy in front of Vault that rewrites responses.

Resolution: Check the login response of your secrets manager and set Token JSONPath to where the token actually is.

The Token JSONPath Is Not a Valid Expression

The banner reads The configured token_jsonpath [...] is not a valid JSONPath expression: ....

Cause: The Token JSONPath has a syntax error, for example an unbalanced bracket or a missing $.

Resolution: Correct the expression. For Vault it is $.auth.client_token.

The Token JSONPath Points at an Object, Not a Token

The banner reads The path [...] in the secrets manager's login response must resolve to a scalar token value, but returned [dict] (or [list]).

Cause: The expression selects a whole object rather than the token string inside it, for example $.auth instead of $.auth.client_token.

Resolution: Extend the expression down to the field that holds the token.

The banner reads The secrets manager login response returned a successful response that was not valid JSON: [...].

Cause: The Login URL answered with something other than JSON, often an HTML page from a proxy, a sign-in portal, or a wrong path that serves the Vault web UI.

Resolution: Point the Login URL at the API path, /v1/..., not at the UI, and check that no proxy on the way rewrites the response.

Fetching the Secret

Permission Denied

The banner reads The secrets manager fetch attempt failed. It responded with: [403: Forbidden - [... permission denied]].

Cause: The role's token cannot read the secret. Either no policy grants read on the secret's data path, the policy path is wrong (for example missing the /data/ segment on a KV version 2 mount), or the policy is not attached to the role.

Resolution: Fix the policy path, attach the policy with token_policies on the role, then mint a new secret ID so a fresh token carries it. The verification step in Prepare Vault confirms the fix from the CLI.

The Secret Was Not Found

The banner reads The secrets manager fetch attempt failed. It responded with: [404: Not Found ...].

Cause: The Secret URL path is wrong: the mount name, the secret name, a missing namespace, or a missing /data/ segment on a KV version 2 mount.

Resolution: Copy the API path from the secret's Paths tab in the Vault UI and put https:// and the host in front of it.

The Data JSONPath Was Not Found in the Response

The banner reads The path [...] was not available in the secrets manager's fetch response. It contained these keys: [...].

Cause: The Data JSONPath does not match the shape of the response. The keys listed in the message tell you what the response looked like.

Resolution: Use $.data.data for a KV version 2 secret and $.data for KV version 1 or the database secrets engine. See Choosing the Data JSONPath.

The Data JSONPath Is Not a Valid Expression

The banner reads The configured data_jsonpath [...] is not a valid JSONPath expression: ....

Cause: The Data JSONPath has a syntax error.

Resolution: Correct the expression. For a KV version 2 secret it is $.data.data.

The Data JSONPath Points at a Single Value

The banner reads The path [...] in the secrets manager's fetch response must resolve to a key-value object, but returned [str] (or another type).

Cause: The expression selects one value, for example $.data.data.password, instead of the object that holds all the key/value pairs.

Resolution: Stop the expression at the object, $.data.data, and pick individual values in the connection fields with ${key}.

The Fetch Response Is Not JSON

The banner reads The secrets manager fetch response returned a successful response that was not valid JSON: [...].

Cause: The Secret URL answered with something other than JSON, usually because it points at the Vault web UI or at a proxy page rather than the API path.

Resolution: Use the API path from the secret's Paths tab, which starts with /v1/, with https:// and the host in front.

Using the Secret

The Only Keys Available Are `data` and `metadata`

The banner reads The datastore configuration references secret token(s) that could not be resolved: ${...}. ... Keys available in the secrets context: data, metadata.

Cause: The Data JSONPath is $.data on a KV version 2 secret, so Qualytics received the wrapper object rather than the key/value pairs.

Resolution: Set Data JSONPath to $.data.data.

A Reference Could Not Be Resolved

The banner reads The datastore configuration references secret token(s) that could not be resolved: ${...}. Please check for typos in your token name(s). Keys available in the secrets context: ....

Cause: The name inside ${...} does not match a key in the secret. Key names are case sensitive.

Resolution: Use one of the listed keys exactly as written, or add the missing key to the secret.

A Reference Is Rejected Over Its Key Name

The save or the connection test fails with a message saying that secret token names may only contain letters, digits, and underscores, naming the reference, for example ${some-key}.

Cause: The key name is one ${key} cannot reference. Only names that start with a letter or underscore and contain letters, digits, and underscores can be substituted. In a file field, in Private Key Password, or in the Hive Client Principal, a name with a hyphen, dot, or other character is refused before anything is sent to the data source.

Resolution: Rename the key in the secret to use underscores, for example service_account, and update the reference. See Referencing the Secret.

A Reference Stays in a Text Field as Literal Text

The connection test or a later operation fails with the data source rejecting a value that still reads ${some-key}, and no Qualytics message about the reference appears.

Cause: The same key name problem in an ordinary text field, such as a username or password. The key exists in the secret, so the reference passes the check for unknown keys, but a name with a hyphen, dot, or other character is never substituted and reaches the data source as typed.

Resolution: Rename the key in the secret to use underscores, for example service_account, and update the reference. See Referencing the Secret.

The Data Source Rejects a Value That Looks Like `$.key`

The banner shows an error from the data source itself quoting the literal text, for example Value '$.role' at 'roleArn' failed to satisfy constraint from AWS.

Cause: The field uses JSONPath syntax instead of a reference, so the text was sent to the data source unchanged.

Resolution: Write the reference with braces, ${key}. See Referencing the Secret.

The Test Passes but Later Operations Fail

Syncs, profiles, or scans fail against a datastore whose connection test used to pass.

Cause: Qualytics logs in to Vault and fetches the secret on every use. A secret ID that has expired or run out of uses, a revoked policy, or a firewall change breaks every later operation, not only new connection tests.

Resolution: Run Test connection on the connection to get the current message, then follow the matching entry on this page.