Troubleshooting
Essential first-use checks.
This page covers the shortest useful checks for installation, data registration, AI-client setup, and evidence review. It is not an exhaustive error catalog.
Install or Python version problem
Symptom: pip install vnuli fails or Vnuli does not run.
Check: Vnuli 0.1 is qualified on Windows 11 x86-64 with Python 3.12.
Next action: Confirm Python with python --version, then install again in the environment you intend to use.
vnuli command not found
Symptom: The vnuli command is not found.
Check: The Python environment where Vnuli was installed may not be active or on PATH.
Next action: Activate the environment, then run vnuli --version and vnuli --help.
Project setup issue
Symptom: vnuli setup fails or later commands cannot find project state.
Check: Run setup from the folder where you want Vnuli project state to live.
Next action: Re-run vnuli setup in that folder and avoid manually editing the local Vnuli state.
Data source is unsupported or ambiguous
Symptom: vnuli data add <source> rejects a file or reports unsupported/clarification-needed behavior.
Check: Vnuli supports documented layouts, not arbitrary files by extension.
Next action: Compare the file to Supported Data. For CSV, the first column must be exactly time and every other column must be numeric.
Understanding vnuli data show
Symptom: Vnuli's interpretation is surprising.
Check: Review the dataset id, run ids, channel ids, timebase behavior, units, metadata, limitations, and provenance shown by vnuli data show <dataset>.
Next action: If Vnuli reports unknown units or explicit irregular time, treat that as Vnuli preserving the available source truth rather than guessing missing engineering meaning.
AI client does not discover Vnuli
Symptom: Your AI client shows no Vnuli tools.
Check: Install and verify the client registration from the initialized project folder.
vnuli mcp install <client>
vnuli mcp list
vnuli mcp verify <client>Next action: Restart or reload the AI client if needed. In the qualified GitHub Copilot/VS Code environment, the user manually started the Vnuli MCP server from MCP: List Servers.
vnuli serve does not resolve
Symptom: vnuli mcp verify <client> reports that configuration exists but the server command does not resolve.
Check: The client process may not have the Python environment containing vnuli on PATH.
Next action: Launch the AI client from a shell where vnuli --version works, or reinstall Vnuli in the environment the client can see.
What mcp verify does and does not prove
Symptom: Verification passes but the AI client still cannot use Vnuli.
Check: Vnuli verification checks local client configuration and whether vnuli resolves on PATH. It does not claim real AI-client workflow qualification.
Next action: Open the AI client and confirm it can see Vnuli tools, discover registered data, and invoke a representative Vnuli engineering operation.
Evidence or result looks wrong
Symptom: An AI response does not match what you expected.
Check: Inspect the Vnuli evidence before trusting the AI explanation:
- dataset;
- run;
- channel;
- time window;
- method/calculation;
- warnings;
- provenance;
- Vnuli's interpretation from
vnuli data show <dataset>.
Next action: Ask the AI to show the Vnuli evidence it used. Vnuli is the deterministic numerical layer; the AI explanation should be checked against Vnuli evidence. Vnuli does not guarantee that the underlying source data itself is correct.