keyshroud

Troubleshooting

Start with keyshroud doctor. It prints which vault is in use, whether it is open, every wired name and whether it resolves, and the state of the Claude Code pieces. Names only, never a value.

backend=local (/home/you/.config/keyshroud/backend says local)
local vault=~/.config/keyshroud/vault.json key=keychain status=unlocked items=12
/home/you/.config/keyshroud/env.json GH_TOKEN resolved=yes
redact index=present
apiKeyHelper wired=no
claude guard=off

A line that says status=locked or resolved=no is the place to look.

A secret does not resolve

Message What it means Fix
Secret unresolved: NAME is not wired (exit 4) No variable of that name points at a vault item keyshroud list to see what is wired; keyshroud add --env NAME --item "Item" or keyshroud wire --env NAME --item "Item"
Secret unresolved: NAME is outside this project's scope (…/.keyshroud.json) (exit 4) A project scope in this directory leaves that name out Run the command where the name belongs, or widen the scope yourself: keyshroud scope --only '…'. An agent should ask you, not edit the file
keyshroud: unresolved (names only): NAME A reference in a --refs file points at an item that does not exist here; the command still runs, without that variable Check the item's name in .env.refs against keyshroud list; a teammate's vault may not have it yet
keyshroud: unresolved (names only): NAME (The local vault is locked: …) The vault could not be opened, so the command ran without that variable See the next section
Secret unresolved: NAME (…) from run --only NAME (exit 3 or 4) The name you asked for did not resolve, so the command was not run: 3 when the vault could not be unlocked, 4 otherwise The reason is in the brackets; fix it and run the command again
Ambiguous vault item name: NAME (exit 4) Two items share that name Rename one of them in the vault
node: FILE: not found (exit 9) The file was named with --env-file, and Node.js 20.6 or later read that flag itself before keyshroud started Use --refs FILE, and check the path

The vault is locked

A keychain, Secret Service or DPAPI vault opens by itself. A passphrase or Touch ID vault, and Vaultwarden, have sessions of 30 minutes:

  • In a terminal, the command asks again.
  • From an agent on your desktop, a dialog opens. If you cancel it, the command still starts, without the secrets, and keyshroud prints unresolved (names only): NAME (Cancelled); with --only NAME it does not start, and exits 3. No second dialog opens for 30 seconds, and the agent should not ask again by itself.
  • Over SSH or without a display, no dialog can open: the same line says The local vault is locked: run `keyshroud unlock` in a terminal. Do that, then run the command again. No terminal and no dialog here (SSH or no display) from add or rotate is the same situation: run it in a terminal, or pipe the value with --stdin.
  • keyshroud status exits 3 while the vault is locked, which is handy in a script.
  • The Linux keyring is locked: you are logged in over SSH without a desktop session. Unlock the keyring, or give that machine a passphrase vault: keyshroud rekey --to passphrase.
  • Windows over SSH, Access is denied: a key-based SSH login carries no Windows password, so DPAPI refuses. Use the desktop or RDP session, or a passphrase vault.

A value was printed unmasked

Check these in order:

  1. The command was run with --no-mask, or with keyshroud before 0.13 on a terminal. --no-mask hands the terminal to the command and masks nothing. Before 0.13, keyshroud run masked only when its output was not a terminal, and Gemini CLI, Cline and other agents that run commands on a pseudo-terminal got the values as they were: update with npm i -g keyshroud@latest.
  2. The command failed, in Claude Code, and the guard is off. Claude Code's hook cannot rewrite the output of a failed command. Run secret-using commands through keyshroud run, or turn on the guard: keyshroud claude-guard.
  3. The agent has no hook. Only Claude Code and pi/omp mask commands you did not wrap. In Codex, Cursor, OpenCode and Gemini CLI, masking happens inside keyshroud run.
  4. The value is not in the vault. keyshroud masks the values it holds. A key that lives only in a .env file is unknown to it: move it.
  5. The value was changed on the way out. Masking is exact-match: a part of the value, base64 or another encoding of it is not recognised. Values shorter than 6 characters are never masked.
  6. You rotated it. After keyshroud rotate, the old value is no longer known; see rotate a key.

If none of these fit, that is a bug worth reporting: see SECURITY.md.

An interactive program gets no terminal

keyshroud run masks what a command prints, so the command writes into a pipe. A program that wants the terminal itself (psql, ssh, an editor, an agent's interface such as claude) then shows no prompt, loses its colours, or says its output is not a terminal. Start it with --no-mask:

keyshroud run --no-mask -- psql

It gets the terminal, and nothing it prints is masked: this is for you, in your own terminal, never for a command an agent runs.

Claude Code

  • Nothing happens after installing or updating the plugin. Hooks load when a session starts: restart Claude Code. The hooks call the keyshroud on your PATH, so keyshroud --version in a terminal tells you which version they run.
  • The agent does not know my secrets' names. The SessionStart hook lists the wired names that are in scope for the directory the session started in. keyshroud env shows the same list.
  • With the guard on, a command exits 126 without running. The guard could not start its masking process or read Claude Code's settings, and it does not run a command it cannot mask. The message says which. keyshroud claude-guard --off turns it off; sessions that are open keep working.
  • The guard is on but old sessions are not masked. It takes effect in sessions started after keyshroud claude-guard.

Vaultwarden and Bitwarden

  • bw login prints KeyIdBackfillError. bw 2026.9 and later call an endpoint that Vaultwarden added in 1.37.4. The login is saved anyway; update Vaultwarden to make the error go away.
  • A copied bw data directory logged the original out. A copy shares one refresh token with the original, and the server accepts each token once. Do not copy that directory between machines: sign in on each one with keyshroud setup --registered.
  • More in Vaultwarden or Bitwarden.

Team secret managers

Exit 3 from a vault://, op://, awssecrets:// or similar reference means the source did not accept the sign-in: the token expired, or the vendor CLI is logged out. keyshroud source lists what is set up and which CLIs it found; sign in the way you normally do (op signin, aws sso login, gcloud auth login, az login) and run the command again. Details per source: team secret managers.

Still stuck

Open an issue at https://github.com/dinhkarate/keyshroud/issues with the output of keyshroud doctor and keyshroud --version. Both print names only, so they are safe to paste.

Edit this page on GitHub · Markdown