Troubleshooting zn-gate

The eleven messages people most often meet when they first use zn-gate: what each one means and what to do. Each message is copied as zn-gate prints it. A part in angle brackets, such as <agent>, is a blank that zn fills in for you. Messages are quoted as zn-gate 1.13.1 prints them.

Run every command in your own terminal, not through your AI agent. Words you do not know are in the glossary.

1. Node.js is too old

zn-gate needs Node.js 18 or later, and this is Node.js v12.22.9.
Install the LTS version from https://nodejs.org/ (or run: nvm install --lts), then run the command again.

What it means: zn-gate is a Node.js program and your computer has a version that is too old. The version number in the message is yours and will differ.

What to do:

1. Install the LTS version from nodejs.org, or run nvm install --lts if you use nvm.
2. Open a new terminal and check with node --version. It must say 18 or higher (the LTS version is recommended; the Claude Code plugin needs 20.12 or later).
3. Run your command again.

2. npx: command not found

What it means: Node.js is not installed, or this terminal was opened before you installed it. npx and npm come with Node.js.

What to do: install the LTS version of Node.js, open a new terminal and run the command again. Check with npx --version.

3. "running scripts is disabled on this system" (Windows)

What it means: Windows PowerShell blocks the script that starts npm and npx by default. Nothing is wrong with zn-gate.

What to do, any one of these:

• Use the .cmd versions: npx.cmd -y zn-gate init, or npm.cmd install -g zn-gate.
• Run the same commands in Command Prompt instead of PowerShell.
• Allow local scripts for your account: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

More in the README.

4. It needs you at your own terminal

You may see one of these:

zn hooks: Not allowed: zn hooks install needs an interactive terminal.
zn env: Not allowed: zn env shadow needs an interactive terminal.
<command> must be run by you in your own terminal, not by an AI agent (detected CLAUDECODE).
An AI agent is running this, so zn only prints the steps: installing hooks is your decision. Nothing was changed.

What it means: some steps change your settings or touch your secrets, so zn only runs them when a person types them. It refuses when your AI agent runs them, or when a script runs them with nobody at the keyboard. This is on purpose. Nothing was changed.

What to do: open a terminal window yourself (not the agent's window) and run the same command there. If you only see "started from ...", zn thinks an agent is above your terminal in the process chain. Open a fresh terminal window from your system menu and try again. For init, the steps printed under the message are the commands to run.

5. "Your secret vault is locked"

Your secret vault is locked. Unlock it in this terminal with: zn unlock. Then run this command again.

What it means: zn keeps the real values of your secrets in an encrypted vault, and the vault is closed. It locks itself after 30 minutes without use, after 8 hours at most, or when you restart your computer. If zn is not installed on your computer, the message gives the npx -y zn-gate@<version> unlock form instead.

What to do:

1. Run zn unlock in your own terminal. It may ask for a passphrase. Type it yourself: zn never reads it from your agent.
2. Run zn vault status to see that it says unlocked.
3. Run the command that failed again.

More in secrets. If it asks for a terminal to enter the passphrase and you have none (for example over SSH), that page explains how to run the vault in a terminal of its own.

6. Your agent was blocked: ".env holds plain-text secrets"

zn: .env holds plain-text secrets. Ask the user to run `zn env shadow .env` in their terminal: it moves the values to the local vault and leaves __ZN_<NAME>__ markers you can read and use.

What it means: your agent tried to read a file with secrets in plain text. zn stopped it, so the secrets did not reach the agent. This is zn working, not an error.

What to do:

1. If the agent needs a value from that file, run zn env shadow .env yourself in your own terminal. The values move to the vault and the file keeps markers such as __ZN_API_KEY__ that the agent can use.
2. If you did not expect the read, ask your agent why it wanted that file, and do not look for a way around the block.
3. To put your old .env back, run the restore command that zn env shadow printed, for example zn env unshadow .env --backup <name>.

More in secrets and what the check means.

7. Your agent ignores zn's hooks on a managed computer

Your organization's Claude Code policy (<file>) turns off all hooks (disableAllHooks), so zn's hooks do not run. Claude Code does not show this. Ask your administrator to add zn to the managed settings.

Other versions say that the policy "runs only the hooks in its managed settings (allowManagedHooksOnly)", that a settings file of yours "sets disableAllHooks", or that a managed MCP list does not include zn's "secrets" server.

What it means: a setting stops zn's hooks from running. Usually your company or school controls Claude Code's settings; sometimes it is a line in your own settings file. Claude Code itself shows no warning, so zn tells you when you install hooks or run npx -y zn-gate check or npx -y zn-gate status. Until this is fixed, zn is not protecting that agent.

What to do:

• If the message names your own settings file, that line turns off every hook you install, zn's included. Remove the disableAllHooks line, unless you set it on purpose, and run npx -y zn-gate check.
• If it names an organization policy, ask your administrator to add zn to the managed settings. Send them the message.
• Run npx -y zn-gate check to see which agents are protected.

More in compat.

8. zn-gate connect does not accept your key

That does not look like a zn API key (they start with zn_). Nothing was saved.
usezn.com did not accept this key (it may be revoked or mistyped). Nothing was saved.
This key can do more than analyze text, and zn-gate only accepts a key limited to analyzing. Create an analysis-only key on the connect page and paste that one: <connect page address>
Nothing was saved.

What it means: connect is optional and turns on the cloud check. It saves a key only if the key is an analysis-only key that works. The message says which part failed. Nothing was saved, so nothing needs undoing.

What to do:

1. Create a new analysis-only key on the connect page named in the message. Do not use a full-access key.
2. Run zn-gate connect and paste the key at the hidden prompt. Never put the key on the command line.
3. To turn the cloud check off at any time: zn-gate disconnect.

More in connect. You do not need connect to use zn-gate: without it everything stays on your machine.

9. "will not send the saved key" (TLS settings)

NODE_TLS_REJECT_UNAUTHORIZED=0 is set, so zn-gate will not send the saved key over a connection whose certificate is not checked

What it means: your terminal has a setting that turns off the check of website certificates, changes how secure connections work, or could print or read your key. zn-gate refuses to send your saved key through such a connection. Similar messages name NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, OPENSSL_CONF, NODE_DEBUG or NODE_OPTIONS instead. Your local checks keep working.

What to do: zn-gate refuses on purpose: with that setting, someone between you and usezn.com could read your key. Nothing is broken, and the local checks keep working without the cloud check.

• If you set it yourself, for example for a test, remove it, open a new terminal and try again. On macOS or Linux, unset NODE_TLS_REJECT_UNAUTHORIZED (or the name in the message) removes it for this terminal. If it comes back, look in your shell startup file (such as ~/.zshrc or ~/.bashrc).
• If your company needs it, for example for a proxy with its own certificate, keep it and ask your administrator. Until then zn-gate uses only its local checks on this computer.
• Never turn off certificate checks to make this message go away.

10. "the evidence log ... is damaged"

zn-gate: the evidence log <path> is damaged (<reason>) Events are not being recorded. Run 'zn-gate evidence --verify' for details. To start a new log and keep the old file for review, move it aside (mv "<path>" "<folder>/evidence.damaged.jsonl"); the next event starts a new chain.

What it means: zn-gate keeps a log of what it decided. Each line is linked to the one before, so a line that was edited, cut off or half written breaks the chain. zn does not repair a log: it stops writing to it so it never hides the damage. Your protection keeps working. Only the record stops. On Windows the message shows a move command instead of mv.

What to do:

1. Run npx -y zn-gate evidence --verify. It says where the break is.
2. Keep the old file if you need it for review. Move it aside with the command in the message.
3. The next event starts a new log. Run npx -y zn-gate evidence --verify again to see that it is fine.

11. The Claude Code plugin needs a newer Node.js

You may see one of these. The first comes from npx -y zn-gate check, the second from npx -y zn-gate init:

X  Claude Code   NOT protected: the zn-gate plugin needs Node.js 20.12 or later (you have 18.19.1).
Claude Code plugin skipped: it needs Node.js 20.12 or later (you have 18.19.1). zn's hooks are set up instead; update Node.js to use the plugin.

The version number in the messages is yours and will differ.

What it means: the zn-gate plugin for Claude Code needs Node.js 20.12 or later. With an older Node.js (for example Node.js 18, which apt installs on many Debian and Ubuntu systems), the plugin does not work on purpose, and Claude Code may list its MCP servers as failed to connect. zn-gate itself and zn's hooks still run on Node.js 18 and later. Nothing is wrong with your files.

How to check:

1. Run node --version in your own terminal. If it says a version lower than 20.12 (such as v18.19.1), this is the cause. Claude Code starts the plugin with the first node on its PATH, so use the terminal you start Claude Code from.
2. Run npx -y zn-gate check. A line for Claude Code that says NOT protected: the zn-gate plugin needs Node.js 20.12 or later confirms it.

What to do, either one:

• Update Node.js (recommended): install the Node.js LTS version from nodejs.org, open a new terminal, check that node --version shows it, then start a new Claude Code session. On a computer with several Node.js installs, make sure the new one is the first on your PATH.
• Or use zn's hooks instead of the plugin: run npm install -g zn-gate, then zn hooks install claude-code, then claude plugin disable zn-gate@usezn, all in your own terminal. Then run npx -y zn-gate check again.

Running npx -y zn-gate init on a Node.js older than 20.12 does the second option for you: it skips the plugin and sets up zn's hooks for Claude Code instead, and if the plugin is already installed it turns it off once the hooks work.

Also useful

• Your agent blocks every prompt after you upgraded or removed Node.js: see If your agent blocks every prompt.
• Not sure what is protected: npx -y zn-gate check, explained in check.
• Still stuck: ask in Discussions. Say your zn-gate version (zn-gate --version), your operating system and the message, and leave out any secret.