Developers · CLI
Insites CLI Troubleshooting
Last updated 18 November 2026
Fixes for common Insites CLI problems: Node version, install permissions, sign-in errors, rate limits and file watchers.
Fixes for the problems people meet most often with the Insites CLI 6.4.1. Start with insites doctor: it checks Node.js, the .insites file, each environment's sign-in and the site, and prints the command that fixes each problem.
insites doctor # every environment
insites doctor staging # one environment
insites doctor --json # for scripts and AI agentsIt never prints a key or token, so its output is safe to paste into a support request.
The CLI Says It Needs Node 22 or Newer
Check your version with node --version, then upgrade with the tool you use:
- nvm:
nvm install 24 && nvm use 24 - fnm:
fnm install 24 && fnm use 24 - Homebrew on macOS:
brew install node@24 - Windows: download the LTS installer from nodejs.org, run it, then open a new terminal.
Then install the CLI again with npm i -g @insites/insites-cli.
npm Permission Errors (EACCES) on Install
Do not use sudo. Tell npm to install global packages in a folder you own:
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-globalAdd ~/.npm-global/bin to your PATH, for example in ~/.zshrc or ~/.bashrc, open a new terminal and install again. A Node version manager such as nvm or fnm avoids the problem, because it installs Node in your home folder.
The insites Command Is Not Recognized on Windows
Global npm commands live in the folder that npm config get prefix prints, usually %AppData%\npm. Add that folder to your user PATH in Settings, System, About, Advanced system settings, Environment Variables, then open a new terminal. If PowerShell blocks scripts, run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.
No Environments Registered Yet
There is no environment in .insites for this project. Add one:
insites env add staging --instance-uuid <instance-uuid>Commands look for .insites in the current folder, then in each parent folder up to the git root. If you still see this message, you are probably in another project, or the .insites file is outside the git repository.
401 or 403 From the Site
Your sign-in has expired, or your access was removed. Sign in again for that environment:
insites env refresh-token <environment>For an environment that uses an access token, create a new token on the site's CLI Commands tab in the Insites Console and run insites env add again with it. Deploying and syncing need the Developer role on the site.
503, 429 or Rate Limited
The site is busy or is limiting requests. Wait a minute and run the command again. For sync, lower the load with --concurrency 1. For a large deploy, deploy fewer files at a time with --partial-deploy. If it keeps happening, tell Insites support which site and what time.
A Command Waits Too Long
Every request has a time limit: 30 seconds, or 10 minutes for uploads, downloads and long jobs. When it runs out, the command says which host did not answer. To give one command or a whole pipeline longer, set INSITES_TIMEOUT in seconds:
INSITES_TIMEOUT=90 insites exec graphql staging --file report.graphqlSync Fails With EMFILE or ENOSPC
Both mean your computer ran out of file watchers or open files.
- EMFILE (too many open files), macOS and Linux: raise the limit for this terminal with
ulimit -n 10240, then run sync again. - ENOSPC (Linux): raise the watch limit:
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf sudo sysctl -p
Sync already leaves out node_modules, .git and everything in .insitesignore. Add other large folders to .insitesignore, and run insites sync <environment> --verbose to see how many paths are left out. Sync prints the fix once and keeps running, but it can miss changes until you raise the limit and restart it.
A Message Says a Newer Version Is Available
The CLI checks once a day. To update, run npm i -g @insites/insites-cli@latest. To turn the message off, set INSITES_NO_UPDATE_NOTICE=1.
Seeing the Full Error
For an expected problem, the CLI prints what happened and what to do, without a stack trace. To see the full details, run the command again with DEBUG=1 in front. Tokens in that output are shortened to their first six characters.