# 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. Source: https://usezn.com/docs/zn-gate/troubleshooting/ 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 ``, 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](https://usezn.com/docs/glossary/). ## 1. Node.js is too old ```text 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](https://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](https://nodejs.org/), 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](https://github.com/usezn/zn#install). ## 4. It needs you at your own terminal You may see one of these: ```text zn hooks: Not allowed: zn hooks install needs an interactive terminal. zn env: Not allowed: zn env shadow needs an interactive terminal. 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" ```text 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@ 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](https://usezn.com/docs/zn-gate/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" ```text 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___ 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 `. More in [secrets](https://usezn.com/docs/zn-gate/secrets/) and [what the check means](https://usezn.com/docs/check/). ## 7. Your agent ignores zn's hooks on a managed computer ```text Your organization's Claude Code policy () 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](https://github.com/usezn/zn/blob/main/docs/compat.md). ## 8. `zn-gate connect` does not accept your key ```text 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: 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](https://usezn.com/docs/zn-gate/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) ```text 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" ```text zn-gate: the evidence log is damaged () 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 "" "/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`: ```text 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](https://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](https://github.com/usezn/zn/blob/main/docs/compat.md#if-your-agent-blocks-every-prompt). - Not sure what is protected: `npx -y zn-gate check`, explained in [check](https://usezn.com/docs/check/). - Still stuck: ask in [Discussions](https://github.com/usezn/zn/discussions). Say your zn-gate version (`zn-gate --version`), your operating system and the message, and leave out any secret.