Vault "namespace not found" (Enterprise VAULT_NAMESPACE) in CI

On Vault Enterprise, every request is scoped to a namespace. If VAULT_NAMESPACE is missing or wrong, the mount and secret you expect are invisible, and Vault reports the namespace or route as not found.

What this error means

A read fails with "Code: 404 ... * namespace not found" or "no handler for route", and works only once VAULT_NAMESPACE is set to the right namespace.

Error making API request.

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

* namespace not found

Common causes

VAULT_NAMESPACE is unset or wrong

Without the namespace, the request runs in the root namespace where the mount does not exist, so the path is not found.

The namespace path is misspelled or nested wrong

Enterprise namespaces nest (team/ci). A wrong or partial namespace path resolves to nothing.

How to fix it

Set VAULT_NAMESPACE for the job

1. Confirm the namespace that owns the mount with an operator.
2. Set VAULT_NAMESPACE in the workflow env (including nesting like team/ci).
3. Re-run and confirm the path resolves.

env:
  VAULT_NAMESPACE: team/ci

Pass namespace to hashicorp/vault-action

The action takes a namespace input for Enterprise.

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

How to prevent it

• Always set VAULT_NAMESPACE explicitly on Enterprise; do not rely on root.
• Store the exact nested namespace path, including parents.
• Document which namespace each CI mount lives in.

Related guides