Skip to content

Troubleshooting ​

Start with the message klars shows. Model setup, a service connection, and an agent sign-in are separate pieces; an error in one does not always require restarting the whole app.

macOS blocks the app ​

Current DMGs are unsigned and not notarized. For an app obtained from a trusted channel, right-click klars.app in Finder and choose Open. If it remains blocked:

sh
xattr -dr com.apple.quarantine /Applications/klars.app

Use the actual installed name; the first release was klars Local.app. See Install klars.

Windows protected your PC ​

Current Windows artifacts are unsigned. For a trusted copy, choose More info → Run anyway in SmartScreen. For the portable release, extract the entire ZIP before opening klars.exe.

Python or model libraries are missing ​

Open Graph actions → Model setup → Python environment and select an absolute interpreter path. Confirm that it is the environment containing your model’s dependencies.

An app launched from Finder does not see your shell’s activated virtual environment. Python and PyTorch are not bundled. For Hugging Face, Transformers must also be installed in the selected environment; klars names this when it is missing and offers a reviewed install.

For headless launches, set KLARS_PYTHON before starting the service. The CLI’s initial Python check does not validate all model imports.

A capture fails ​

Review the model entry point, example input shapes and types, and the Python environment in Model setup. Read the failure card’s reason before trying again.

For a Hugging Face model, check whether the architecture is supported by the installed Transformers version. For a gated model, accept its conditions on Hugging Face and provide a read token. A random-weight build above the memory guard is refused; it is not a successful capture.

The terminal is blank ​

Open a model first, then choose Terminal → New terminal. Confirm that Terminal session contains a selected shell. Use Refresh terminals after a reconnect.

If the workspace lost its service connection, reconnect before opening another shell. Older macOS packages omitted a native terminal dependency; current packages include it. Update an older release before investigating your shell configuration.

The workspace cannot start ​

For desktop, inspect its service log:

sh
# macOS
 tail -n 80 "$HOME/Library/Application Support/klars/service.log"

On Windows, open %APPDATA%\klars\service.log.

Check whether another service already owns the chosen data directory or port. For klars serve, read the terminal diagnostic. A stale-lock message includes recovery instructions: verify that the recorded process is gone before removing the lock.

The browser shows an older interface ​

Reload after reconnecting to the running service. If you are using a built browser workspace, make sure you are visiting that service’s current address. A previously cached page can remain viewable offline, but operations needing the service will not work until it reconnects.

The layout or custom style is hard to use ​

Search for Reset layout for panel positions and pins. To pause custom CSS in the browser, add ?ui=default to the address for one load. Then use Settings › Appearance › Customization › Reset customization.

Invalid customization files are named in Settings, with the last good version kept on screen. See customization.

The secret store is locked ​

Open klars desktop on the computer holding the store, or have the headless operator provide the correct existing vault key. Do not generate a replacement key over the existing store. Secrets & credentials →

Your models. Your machine. Your next idea.