Troubleshooting

Troubleshooting

Start by finding which layer is actually failing: the environment, app startup, runtime, provider, model, or an optional integration.

Source setup or environment fails

Run the development doctor from the application repository root.

Native Windows PowerShell:

.venv\Scripts\python.exe scripts/dev-doctor.py

Linux / WSL compatibility paths:

.venv/bin/python scripts/dev-doctor.py

Fix toolchain or environment errors first. There is little value debugging the app on top of a setup the doctor already says is invalid.

See Prerequisites.

Application UI does not load

The normal development frontend is expected at:

http://localhost:5173

The backend uses port 8000 by default.

Confirm the root launcher is still running and inspect application logs before starting additional copies.

Managed model server fails to start

Check:

• selected profile/model asset still exists;
• configured/managed llama-server binary is available;
• assigned port is free;
• runtime configuration is compatible with the installed binary;
• available CPU/GPU/VRAM resources are sufficient;
• Model Manager/runtime logs contain the real startup error.

Do not repeatedly start more model processes while the previous failure is still unclear.

Model is too large for available memory

Use a smaller model/quantization or a profile that fits the available resources.

Model Manager can estimate VRAM needs, but that estimate is guidance rather than a guarantee that the model will fit.

Provider endpoint is unreachable

Check:

• provider is enabled/configured;
• endpoint URL is correct;
• required credentials/CLI integration are available;
• network access is available where the provider needs it;
• provider connection/status diagnostics succeed.

If the service is managed outside LM Nexus, start, stop, and troubleshoot that service outside Model Manager too.

Direct runtime works but Nexus /v1 does not

That narrows the failure to the integrated serving/provider path rather than the underlying llama-server.

Compare:

• the direct assigned runtime endpoint;
• Model Manager local /v1;
• selected provider/model ids;
• Nexus logs around request resolution/proxying.

See Raw server access.

Native Windows Terminal output is corrupted

Current native Windows Terminal support uses ConPTY/pywinpty.

If you see repeated text such as 1Ignore0011Ignore..., treat that as a failed or stale stream implementation rather than normal terminal output.

Update to the current implementation and re-run the native Windows validation path. WSL remains available as an optional compatibility path, but it is not the current recommended Windows development route.

Where runtime/user data lives

Do not expect models, notes, knowledge, profiles, runtime installs, package state, or normal generated logs to live under repository source paths by default.

LM Nexus uses per-user app-data/config/cache/state boundaries for runtime data.

Reporting issues

Public issue-reporting/community links are intentionally not published yet.

For private-alpha development, include enough detail to reproduce the problem: platform, failing command or workflow, relevant logs, runtime/profile/provider details, and whether it still happens after a clean restart.