Troubleshooting

high/prod injection refused — “not on the executor allowlist”

A high or prod value can only be injected into a reviewed, allowlisted executable. Add it for the run with --allow:

kovra run --env prod --allow ./deploy -- ./deploy

This is separate from the bioProve prompt — it governs where the value may go, not whether you were asked. See the decision process.

A run that delivers a high or prod value also gets a sanitized environment: PATH is fixed to /opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin, and the variables that make a shell, an interpreter or the dynamic loader run extra code (BASH_ENV, ZDOTDIR, NODE_OPTIONS, PYTHONPATH, DYLD_*, LD_*, GIT_SSH_COMMAND, EDITOR, PAGER, …) are dropped. If the program relies on one of them, set it inside the program itself.

kovra allow add refused — “runs whatever script it is given”

Generic interpreters and launchers — sh, bash, zsh, env, python, node, ruby, perl, osascript, make, npm, npx, cargo, docker, … — can’t be allowlisted: allowlisting one would let any script an agent writes receive critical values. Allowlist the reviewed script itself (with its shebang line) instead.

kovra allow list shows “changed since it was approved”

Each allowlist entry pins the content of the program you reviewed. If the file was edited since, it is no longer allowlisted. Review the change and run kovra allow add again.

“the master key in the keyring does not open this vault”

The key in the Keychain is not this vault’s: it was replaced (any program running as you can rewrite that Keychain item with no prompt) or belongs to another vault. kovra neither reads nor seals with it. The message names what does not open: keycheck.sec when the key is not the vault’s, or the records (global/<id>.sec, projects/<name>/<id>.sec) and the shadow list (shadows.sec) that do not — files put in from another vault (at most five, then how many more). If the key is the right one, move the files named out of the vault. Otherwise restore the right key from your backup with kovra key import. key import itself restores only a key that opens the vault’s records — “this backup’s key does not open the vault” means the backup belongs to another vault.

kovra init refused — “holds sealed records but its key is missing”

The vault already holds sealed records, and the keyring has no key for them. Restore the key with kovra key import. kovra init --force (with your approval) starts a new key and leaves those records unreadable. If kovra could not read the key (a cancelled Touch ID, a locked keychain), init stops instead of creating one: run it again.

Edit refused — “two separate edits”

On a critical (high or inject-only) secret, one edit can’t change both its sensitivity and its reference. Make two edits, each with its own approval.

kovra ssh-add refused

ssh-add hands the private key itself to whatever answers at $SSH_AUTH_SOCK, so it refuses high, inject-only and prod keys. Use them through kovra ssh-agent, which signs each request without handing the key out.

the bioProve prompt never appears

On a Mac, kovra asks with Touch ID, or with your login password when the Mac has no Touch ID (or it is not set up). Over SSH, or anywhere without a graphical session, no dialog can be shown: with a paired phone, the request goes to kovra’s approval app on it (kovra Mobile, coming soon); with no paired phone, what needs your approval is refused: run it from the Mac’s desktop. The master key and the pairing are approved only at the Mac. kovra never falls back to an approval an agent could give itself. (KOVRA_CONFIRMER and kovra approve apply to development builds and to platforms other than macOS.)

macOS re-prompts for your login password on every run

If a freshly rebuilt kovra keeps asking for your login keychain password to read the master key, grant the binary standing access: in Keychain Access, find the kovra / master-key item (master-key.<…> for a vault in another folder, see Configuration), and under Access Control allow the kovra application (or “Allow all applications”). This happens because an ad-hoc-signed binary gets a new code identity each rebuild. The signed app from kovra.sh keeps the same identity across updates, so it asks at most once — when you move from an older ad-hoc build to the first signed one (choose Always Allow).

Passphrase mode (KOVRA_PASSPHRASE) is not a way around this on a Mac: kovra refuses it there and keeps the key in the Keychain.

KOVRA_KEYCHAIN_BIOMETRIC refused

KOVRA_KEYCHAIN_BIOMETRIC asks the Keychain itself to require Touch ID on every read of the master key. The kovra app from kovra.sh cannot create such an item yet (it needs a permission the app is not signed with), so it stops with an error before it touches the Keychain, and nothing in your vault changes. Unset the variable (and remove it from your shell profile) and run the command again. Your approvals keep asking with Touch ID as always: this variable only adds a second prompt at the Keychain.

kovra can’t read the master key from the Keychain

• The keychain is locked, or no dialog can be shown (for example over SSH, where the login keychain stays locked): run the command from the Mac’s desktop, logged in, so macOS can unlock the keychain, or unlock it in that session with security unlock-keychain ~/Library/Keychains/login.keychain-db.
• You cancelled the Keychain’s prompt: run the command again and allow it.

kovra never takes a failed read for a missing key: kovra init stops instead of creating a new one.

command not found: kovra

The command isn’t on your PATH. On macOS, open kovra.app and choose Install Command Line Tool… in its menu-bar menu: it creates /usr/local/bin/kovra, pointing into the app (macOS asks for an administrator’s password). kovra setup and kovra doctor tell you when the kovra on your PATH is missing or is another build.

Claude Code needs it too: the MCP server (kovra mcp) and the credential gate’s hooks are registered as kovra …, without a path.

The agent doesn’t see kovra’s tools

After kovra setup, reload your agent so it re-reads .mcp.json. Confirm the server is registered there ("command": "kovra", "args": ["mcp"]) and that kovra is on your PATH (which kovra); in Claude Code, /mcp shows whether kovra is connected. The agent only ever sees scoped metadata — if a coordinate is out of its scope, it’s unaddressable, by design.

“This Claude Code session is not protected by kovra’s hooks”

Inside a Claude Code session, kovra delivers values (kovra run, show, code, decrypt; the MCP inject_run and reveal) only when the session’s settings carry the credential gate’s hooks. Run kovra setup in the project; Claude Code picks the hooks up without a restart. If the reason mentions disableAllHooks or managed settings, see No hooks, no values.

Every prompt is blocked, or tool output arrives as [REDACTED:kovra-unavailable]

The credential gate could not get an answer from kovrad, so it failed closed. The message says why:

• “kovrad is not running and did not start”: run kovra daemon start, check it with kovra daemon status, and send the prompt again. If kovrad keeps stopping, kovra daemon install registers it again to run at login.
• “kovrad is running but did not answer in time”: kovrad runs, but the Mac is very busy. Wait a moment and send the prompt again; if it keeps happening, restart kovrad with kovra daemon stop and kovra daemon start.

It also fails closed when the process answering at kovrad’s endpoint is not the Kaeus-signed kovrad, or for the other reasons in When kovrad cannot answer.

kovra daemon status says launchd does not have kovrad

On a Mac, kovrad starts at login through launchd. When it is registered but launchd does not have it, kovra daemon status, kovra setup and kovra doctor add a note that says why:

• “turned off in System Settings”: kovrad is switched off under System Settings → General → Login Items → Allow in the Background. Turn it on there to have it start at login. Until then kovra starts it only when needed, and does not restart it if it stops.
• “its registration failed”: kovrad is allowed, but launchd did not load it, for example after an update of kovra.app. Run kovra daemon install: it loads kovrad again and returns once kovrad is running.
• When macOS does not say which (before macOS 13), the note gives both causes: check the switch first, and if it is on, run kovra daemon install.

A secret won’t reveal

inject-only secrets are never revealed — they can only be injected. high and prod secrets never reveal to an agent, and reveal at the CLI only after a bioProve. This is the policy working as intended, not a bug; see Sensitivity tiers.