hashicorp/vault-action "failed to retrieve secret" in CI

By Kaveh Alemi·Latchkey

The action authenticated but could not fetch a secret named in the secrets: block. The path, the KV data/ segment, or the key inside the secret is wrong, or the role cannot read it.

What this error means

hashicorp/vault-action fails with "failed to retrieve secret: ... permission denied" or "no handler for route" for one of the mapped paths.

Error: failed to retrieve secret: Error making API request.

URL: GET https://vault.example.com/v1/secret/data/ci/app
Code: 403. Errors:

* permission denied

Common causes

The mapping path or key does not exist

The secrets: line points at a path with no such secret, or names a key (apiKey) that is not present in the secret data.

The role cannot read the mapped path

Auth succeeded, but the role policy does not grant read on secret/data/ci/app, so the fetch is 403.

How to fix it

Fix the secrets mapping syntax

1. Use <mount>/data/<path> <key> | <ENV_NAME> for KV v2 (the action needs data/).
2. Confirm the key exists in that secret.
3. Grant read on the path in the role policy.

- uses: hashicorp/vault-action@v3
  with:
    url: ${{ secrets.VAULT_ADDR }}
    method: approle
    roleId: ${{ secrets.VAULT_ROLE_ID }}
    secretId: ${{ secrets.VAULT_SECRET_ID }}
    secrets: |
      secret/data/ci/app apiKey | API_KEY ;
      secret/data/ci/app dbUrl  | DB_URL

Verify the secret and key exist

Read the path with the CLI to confirm the key name the action expects.

vault kv get -format=json secret/ci/app

How to prevent it

• Match the secrets: path to the KV version (data/ for v2).
• Confirm each mapped key exists in the secret before wiring it.
• Grant read policy on exactly the paths the action fetches.

Frequently asked questions

Related guides

References

• GitHub Actions documentation