Troubleshooting.

Something not working? Start with the diagnostic report, then check the common problems below.

Get a diagnostic report

Inside a session, type /doctor. Outside a session, run:

You get one short block that checks your setup: your Nilux and Node.js versions, whether Nilux can reach its service, each MCP server you have connected, and the files Nilux needs. If you write to support, paste this block into your message.

Nilux does not start

"command not found: nilux": the install did not finish, or npm installs global packages into a folder your terminal does not search. Run npm install -g @nilux-ai/code again and watch for errors.

It stops right away with a syntax error: your Node.js is too old. Nilux needs Node.js 20 or newer; check with node -v and update it from nodejs.org.

On Windows, "requires Git Bash": install Git for Windows. If Git is installed in an unusual place, set the NILUX_GIT_BASH_PATH environment variable to the full path of bash.exe, for example C:\Program Files\Git\bin\bash.exe.

"Folder not trusted; exiting.": you answered no when Nilux asked whether you trust the folder (n, or Enter or Esc, which also mean no). Start it again and press y.

Signing in

• The browser does not open: check that your system has a default browser. You can also set the BROWSER environment variable to the command that opens one.
• Signing in needs a browser on the same computer as Nilux. On a remote machine over SSH, sign in on a computer where you can open a browser.
• "Authentication timed out": the sign-in page waits a few minutes. Start nilux again and finish signing in in the browser.
• "Session expired": type /logout, start nilux again and sign in.

Connection problems

If your network drops, Nilux keeps trying to reconnect and continues where it stopped. Nothing you typed is lost. If it cannot connect at all, check your internet connection, VPN or company proxy, then run /doctor: the Server line shows whether Nilux can reach its service.

Updates

"npm's global directory is not writable": your npm installs global packages into a folder that needs administrator rights. Update with the same command you used to install, run with the rights it needs, or fix npm's global folder.

Pasting images on Linux

To paste an image from the clipboard, Nilux needs wl-paste (Wayland) or xclip (X11). Install one of them with your package manager.

Still stuck?

Write to support@nilux.dev with your /doctor report and a short description of what happened.