Troubleshooting

Find the message you see.

In the agent's chat

If the agent says Claim expired

The claim code ran out: each lasts 15 minutes. Repair the agent and paste the new message.

If the agent says Claim already used

Each code works once. If the agent isn't connected, repair it for a new one.

If the agent says Unknown claim code

It was mistyped, or a newer repair replaced it. Copy the message again from your vault.

If the agent says Agent has been revoked

That agent was removed. Add it again.

If the agent says unauthorized

It has an old connection, usually after a repair. Paste the repair's message into its chat, and remove any WUNDERVAULT_AGENT_TOKEN line from its settings.

If the agent says wundervault-agent is not running for agent …

The helper app isn't running on that computer, or the agent hasn't enrolled. Set up the computer, then paste the message again.

If the agent says an older copy of Wundervault … is still running

Restart the agent's app to close the old copy, then reconnect.

If the agent says WUNDERVAULT_AGENT_NAME is not set.

Its settings don't say which agent it is. Add the setting from Set it up yourself.

On the computer

If the computer says npm isn't found

Install Node.js 22.23.4, 24.22.1 or 26.12.1 or newer from nodejs.org, then open a new terminal.

If it says Node.js lacks the October 21, 2026 security fix

Install Node.js 22.23.4, 24.22.1 or 26.12.1 or newer, then run the step again.

If npm stops with a permission error (EACCES)

On Linux or macOS, run it again with sudo, naming node and npm in full so it works however sudo is set up:

Terminal
sudo "$(command -v node)" "$(command -v npm)" install -g @wundervault/mcp-server@2

If the installer warns that sudo on this computer looks commands up in a folder someone other than root can change

When you type sudo, your computer looks for the command in a list of folders. One of them can be changed by your account, so an agent could put a program there and it would run as root the next time you use sudo for anything. The installer itself is not affected. One line in sudo's settings fixes it for good.

The installer prints four commands with the right folders for your computer: copy them from there and run them one at a time. They write the line to a spare file, check it, and only then put it in place, so a typo can't lock you out of sudo. On a Mac they usually look like this:

Terminal
sudo /bin/mkdir -p /etc/sudoers.d
printf '%s\n' 'Defaults secure_path="/usr/bin:/bin:/usr/sbin:/sbin"' | sudo /usr/bin/tee /etc/sudoers.d/secure_path.new >/dev/null
sudo /bin/chmod 0440 /etc/sudoers.d/secure_path.new
sudo /usr/sbin/visudo -cf /etc/sudoers.d/secure_path.new && sudo /bin/mv /etc/sudoers.d/secure_path.new /etc/sudoers.d/secure_path

Afterwards, sudo /usr/bin/printenv PATH should list only system folders. Don't use sudo visudo for this: it opens an editor as root, and which editor it opens can come from the same settings that are exposed. If the installer says your sudo doesn't read /etc/sudoers.d, the line belongs in /etc/sudoers itself; ask whoever looks after the computer.

After this, sudo npm may say "command not found": on a Mac, npm and node from nodejs.org are in /usr/local/bin, which that line leaves out on purpose (Homebrew can make it writable without sudo). Name both in full instead, as the Mac update steps do:

Terminal
sudo "$(command -v node)" "$(command -v npm)" install -g @wundervault/mcp-server@2

If the app can't start wundervault-mcp

The app doesn't look where npm installs. Find the full path, and use it as the command in the app's settings:

Linux

Terminal
which wundervault-mcp

macOS

Terminal
which wundervault-mcp

Windows

PowerShell
(Get-Command wundervault-mcp).Source

In your vault

If the agent sees no secrets

Most often you haven't let it use any yet: open a secret and turn this agent on under Who can use it (your secrets). Also check the secret and the agent aren't paused, and that its access hasn't ended.

If the agent says a use is waiting

That secret asks you first. Open Approvals in your vault and answer.

If the agent's name has an apostrophe, a quote or a backslash

The vault's message handles it. By hand, type each apostrophe as '\'' in the Claude Code or OpenClaw line (PowerShell: ''), and in a settings file put a backslash before each double quote or backslash.

Still stuck? Tell us what the agent or the page said.