Troubleshooting Zinnector®

The errors people actually hit with the Zinnector® CLI, what each one means, and the fix. Every entry names the exact text you will see, so you can search this page for it. If yours is not here, run the failing command with ZINNECTOR_DEBUG=1 and open an issue at github.com/Zinn-Digital/zinnector/issues with the output, your node --version and your operating system.

"spawn EINVAL" right after accepting the runtime install (Windows)

A bug in Zinnector® 0.1.0 and 0.1.1. On Windows the runtime installer ran npm.cmd by name, and Node has refused to spawn a .cmd file without a shell since its fix for CVE-2024-27980 — so the install crashed one second after you answered Y. Fixed in 0.1.2: npm is now run as node npm-cli.js, which is the same on every platform and needs no shell. Run npm install -g zinnector@latest, then zinnector dev again.

"npm WARN EBADENGINE" during install, or "Zinnector® needs Node 24 or newer"

Your Node is older than 24. npm prints the warning because the package declares engines: >=24.18.1; the install completes anyway, but zinnector then refuses to start (exit code 78) rather than fail somewhere confusing later. Install the current LTS from nodejs.org — winget install OpenJS.NodeJS.LTS on Windows, brew install node@24 on macOS — confirm node --version prints v24 or higher, and install Zinnector® again.

"gyp ERR!", "Building from source with node-gyp", or "You need to install Visual Studio"

The WordPress runtime has a native module whose prebuilt binaries exist for Node 24 and 25 only. On a newer Node (26 and up, as of September 2026) its installer falls back to compiling from source, which on a plain Windows machine ends in a request for Visual Studio. Fixed in 0.1.2: Zinnector® detects this before downloading anything and fetches a Node 24 for the runtime alone — about 30 MB, verified against nodejs.org's checksums — so nothing is ever compiled. If you still see it after upgrading, run zinnector dev --reset-runtime so the half-finished install from before is thrown away first.

"EPERM" warnings from npm while it cleans up (Windows)

Almost always an antivirus scanner or a search indexer holding a file open under the runtime's node_modules while npm tries to remove it. The install is retried from a clean directory on the next zinnector dev; if it keeps happening, zinnector dev --reset-runtime removes the whole runtime directory first and installs again.

"the local playground runtime could not be installed"

The message includes npm's own last lines and the exact command Zinnector® ran, so you can run it yourself and see the full output. The usual causes are a network or proxy problem — the runtime is fetched with your own npm, so npm config set proxy … and a registry mirror apply — or a half-finished earlier install, which --reset-runtime clears.

"the local playground exited before it was ready", or it never becomes ready

Run zinnector dev --verbose to see the runtime's own output. A port already in use is the common one: zinnector dev --port 9401, or set port in zinnector.json. A runtime that installed but will not boot: zinnector dev --reset-runtime. The first boot also downloads WordPress itself, so on a slow connection give it a few minutes; the CLI waits up to five before reporting a timeout rather than hanging.

"this project is not a git repository" on push

Deploys are driven from a repository, so zinnector push needs one with a remote the platform can reach. git init && git add -A && git commit -m initial, add your GitHub or GitLab remote, then zinnector link to connect it to the site.

The site is white after a deploy

Run zinnector check. Nine times in ten it is a PHP version gap — you built on a newer PHP than the slot runs — and the report says which version to switch the slot to with zinnector php <version>, or which to develop against with zinnector dev --php <version>. zinnector logs --error shows the fatal itself.

Related

• Getting started · Local development · Deploying · Command reference