Krasis documentation

Troubleshooting

Practical checks for setup, loading, connections and unexpected output.

A command is not found

On Linux or WSL2, reopen the terminal after installation so it picks up ~/.local/bin, then try krasis-setup and krasis again. Use the current installer if installation did not finish. On native Windows, use the Start menu shortcuts installed by setup.

No usable GPU appears

Check that the NVIDIA driver is installed and that nvidia-smi can see the intended GPU. Krasis requires an NVIDIA Ampere or newer GPU. In WSL2, verify GPU access inside the Linux environment as well as on Windows. If your account has restricted GPU access, confirm its permissions with the machine administrator.

The first launch takes a long time

The first launch downloads or builds dependencies and model caches, then calibrates the runtime. Watch the launcher output or Manager’s startup log for progress. Compatible later launches reuse caches. A large source checkpoint can require substantial disk activity before the server is ready.

The model does not fit

Close other GPU applications, choose a smaller model or reduce the requested context. Check available system RAM as well as VRAM. Use the hardware checker for an estimate and read the actual startup error before changing precision settings.

Do not use --force-load as a normal memory fix: it overrides RAM safety checks. Memory and speed explains the main tradeoffs.

In WSL2, a VM memory cap can hide much of your machine’s RAM. Configure an appropriate memory limit in C:\Users\<YourUsername>\.wslconfig, leaving room for Windows. Apply it with wsl --shutdown from PowerShell after saving your work; this stops running WSL environments.

An app cannot connect

Wait until the model is ready, then test:

curl http://127.0.0.1:8012/health

Use your configured port if it differs. Check that the app’s base URL ends in /v1, that its model ID matches /v1/models, and that the address refers to the server machine. A remote app cannot reach your server through its own 127.0.0.1.

A successful health check confirms the server is reachable; it does not prove that an authenticated inference request will succeed. See Connecting your apps.

Requests return 401

Send the key value, rather than its client name, in Authorization: Bearer <key>. Check that the server account can read the configured JSON file and that it is a nonempty object of valid names and secrets.

After authentication is detected, deleting the file does not disable it: new requests are denied. Fix the file and retry. Edits reload live; API and authentication explains intentional disabling and custom paths.

Answers repeat or tools are unreliable

Try a short plain-text prompt first. Confirm the checkpoint, context and precision match the profile you intended to run. Large agent policies and tool schemas may use most of the available context. Reduce them and reserve room for output.

Text, tool-use and vision support have different evidence. Check ADQ results and the tool-use matrix before treating a result as a client integration bug.

Report a reproducible issue

Include the Krasis version, operating system, GPU and driver, exact model/checkpoint, settings, startup error and a small reproducible prompt. Redact API keys and private input before posting to GitHub Issues.