Troubleshooting

Start with `opensyntax doctor`. It checks provider configuration, model discovery, streaming, git, and workspace health.

EBADENGINE warning

npm warn EBADENGINE Unsupported engine

OpenSyntax requires Node.js 20 or newer. Some dependencies may warn on very new Node versions such as Node 26. Use Node 22 LTS for the most stable CLI experience.

No provider configured

opensyntax auth

Connect a provider before starting chat. You can also use environment variables for temporary sessions.

Provider connected but no response

Run doctor and check provider status, API credits, model name, and base URL.

opensyntax doctor
opensyntax models

Not a git repository

This is not fatal. Git features are disabled for the current folder. Continue normally, run `git init`, or open a project repository.

API key invalid

Re-run provider setup and paste a fresh key. Secrets are not printed back.

opensyntax logout openai
opensyntax auth --provider openai

Global command not found

npm bin -g
npm install -g opensyntax

Ensure the npm global bin folder is on PATH. On Windows, restart the terminal after PATH changes.

Permission denied

Avoid `sudo npm install -g` if using a Node version manager. Fix npm global directory permissions or use `npx opensyntax`.

Terminal commands fail

Run /terminal, /os, /shell, and /path to inspect OS, shell, WSL, Node, and PATH detection. Use /command <cmd> to classify risk before asking OpenSyntax to run a command.

Full OS permission

Commands such as apt install, winget install, brew install, systemctl, netsh, and profile edits require explicit approval. Destructive commands require typed confirmation.