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 NAMEit does not start, and exits3. 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)fromaddorrotateis the same situation: run it in a terminal, or pipe the value with--stdin. keyshroud statusexits3while 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:
- The command was run with
--no-mask, or with keyshroud before 0.13 on a terminal.--no-maskhands the terminal to the command and masks nothing. Before 0.13,keyshroud runmasked 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 withnpm i -g keyshroud@latest. - 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. - 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. - The value is not in the vault. keyshroud masks the values it holds. A key that lives only in a
.envfile is unknown to it: move it. - 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.
- 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
keyshroudon yourPATH, sokeyshroud --versionin 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 envshows the same list. - With the guard on, a command exits
126without 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 --offturns 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 loginprintsKeyIdBackfillError.bw2026.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
bwdata 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 withkeyshroud 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.