Settings and troubleshooting

The four settings tabs, the log file and what to send when you ask for help, the exact error sentences the LU Engine and the trainer can show and what fixes them, the Linux notes, where your files are, and how to reset.

The four settings tabs

Settings opens from the top bar. It has four tabs: "General", "AI Backends", "Agent" and "Voice & Remote". Each section below names the tab and the section heading as they appear, so you can find things with Ctrl+K as well.

General

AI Backends

Agent

Voice & Remote

The log file, and what to send when you ask for help

The app writes one log file per day and keeps the last seven. The card under Settings, General, Troubleshoot reads "LU writes a log every day and keeps the last seven." and asks you to attach today's file to a bug report, because it holds what the app was doing right before the problem, which a screenshot cannot show. It has the buttons "Open folder" and "Copy path". The folder is %LOCALAPPDATA%\lu-labs\logs on Windows and ~/.local/share/lu-labs/logs on Linux, the file is lu.<date>.log with the UTC date, and a crash writes crash.log one level up.

The log records, for every engine start, the port, the context length, the model size, the full command line ("starting the LU Engine llama-server"), the offload decision with the card memory it saw, the layer count and why it chose that, and, if the engine died, its exit code and last lines. So a bug report with the log answers most questions before they are asked.

Above the log card, the probe lists Backends (Ollama, ComfyUI, LM Studio, each Reachable, Not running, Not installed or Error) and Host (LU version, OS, Arch, CPUs, RAM, Disk free (home), VRAM (GPU)). Copy those lines into the report too. Then say which surface (desktop or browser), what you did, what you expected and what happened instead. Do not post private files, credentials or unredacted logs; read the log before you attach it and blank what should not be public.

LU Engine errors

These are the sentences the LU Engine can show, mostly in the chat when a model fails to load, or after "Test" under Settings, AI Backends, Providers. Each is followed by what it means and what to do.

"The LU Engine could not open a local port. Every port it may use between 8127 and 8148 is taken or blocked on this machine. Close whatever is holding them (a llama-server left over from an earlier session is the usual cause), or check whether a firewall or a reserved Windows port range covers that block, then try again." The engine walks from 8127 up to 8148 (skipping 8128, which the embedding server uses) and found nothing free. Quit the app from the tray, check for a leftover lu-llama-server process in Task Manager or ps, end it, start the app again. If no such process exists, reboot.

"The LU Engine could not open port 8127. Another program holds it, or the port sits in a range this system has reserved. The app already tried the next free ports and got the same answer. Close that program or reboot, then try again." Same cause, different symptom. Reboot.

"Port 8127 answers health checks, but the engine this app just started exited immediately. Another llama-server (likely left over from a previous session or crash) is occupying the port. Quit that process or reboot, then try again." An old engine is still answering. End it or reboot.

"The LU Engine started and exited again before it could serve on port 8127. It was tried twice. This looks like a graphics-card problem. Open Settings, LU Engine and set GPU Layers to 0 to run on the CPU, then try again." The engine crashed while putting the model on the card, twice. Update the graphics driver first. If that does not help, set "GPU layers" to 0 under Settings, AI Backends, LU Engine (expert), press "Apply & Restart Engine", and chat on the processor while you sort out the card.

"The LU Engine exited before serving on port 8127. Tried with GPU offload and again on CPU. The log file under Settings, Troubleshoot carries the full command line of both attempts and the engine's own output." The app tried the card and then the processor, and both died. The log has the reason; the last lines of the engine's output are appended to the message. A damaged model file (see the GGUF sentences below) or too little RAM for the model are the usual causes.

"Running on the CPU. The GPU start failed; see the log file in Settings > Troubleshoot." in the status line, with "GPU layers: 0, the GPU start failed" under it. The card failed and the processor took over, so chat works but slowly. Read the log for the card's error, update the driver, then "Apply & Restart Engine".

"The LU Engine did not become healthy on port 8127 within 180s (the budget scales with model size, and huge GGUFs can take minutes on a cold first load)." The engine was alive but not ready in time. The budget is 60 seconds plus 4 per gigabyte, capped at ten minutes. On a slow disk, try once more; the second load is faster because the file is cached.

"The model file "(name)" does not start with the GGUF marker, so it is not a GGUF at all. Open Models, Get new and download it again." and "... carries a GGUF version of (N), which is not a version at all. The file is damaged, most likely a download that did not finish. Open Models, Get new and download it again." The file is not a complete model. Delete it under Models, Installed and download it again. The same sentence with "The vision file next to this model" means the model's second file (the vision projector) is the damaged one.

"Model file not found: (path)" and "The LU Engine has no model file named "(name)". It may have been deleted, moved, or the download did not finish. Open Models, Get new and download it again." The file was moved or deleted outside the app, or the models folder was changed under Model Storage. Put the folder back or download the model again.

"The engine could not read the model file. It may be damaged, cut short, or of a type this engine cannot run. Open Models, Get new and download it again, or pick another model." Appended to a start failure when the engine complained about the file. Same fix as above; if a fresh download fails the same way, the model's format is one this llama.cpp build cannot run, and another quantisation of the same model usually can.

"A system library the LU Engine needs is missing on this machine: libvulkan.so.1. Debian and Ubuntu: sudo apt install libvulkan1. Fedora: sudo dnf install vulkan-loader. On other distributions, install the package that provides libvulkan.so.1. If you installed LU from the .deb or the .rpm, reinstalling also pulls it in." (Linux; the same shape for libgomp.so.1 with libgomp1 or libgomp.) Install the named package.

"The LU Engine program (lu-llama-server.exe) is missing from this installation. Reinstall Locally Uncensored, or pick a different backend in Settings, AI Backends." The engine binary was removed, often by an antivirus. Check the antivirus history (chapter 2), then reinstall.

"The LU Engine started and exited again before it could serve on port 8127. It was tried twice. Reinstall Locally Uncensored if this keeps happening, or pick a different backend in Settings, AI Backends." The general case, with the engine's last twelve lines appended. Read those lines; they usually name the cause.

"The LU Engine is installed but has no chat model to load yet. Open Models, Get new and install one, then test again." After "Test": no model yet. Install one.

"The engine is installed but not started yet. It starts when you pick a chat model, or when you press Test." The "Not running" status. Not an error.

"This model is loaded in the LU Engine right now. Stop the engine or switch to another model, then delete it." When deleting a model. Pick another model first.

"Could not link the model into the LU Engine folder ((reason)). Linking needs source and destination on the same drive. Move the models folder (Settings, Model Storage) to that drive, or copy the file there yourself." Importing a model from another tool works by a link, which cannot cross drives. Either move the LU Engine folder to that drive or copy the file.

Model download and storage errors

"(file) cannot be downloaded without a login at this host (HTTP 401)." (or 403) The model is behind a login on Hugging Face or CivitAI. Paste a Hugging Face token or a CivitAI API key under Settings, AI Backends, then download again.

HTTP 404 or 410 The file was removed from the host. Pick another quantisation or another model.

HTTP 429 The host asks you to slow down. Wait a few minutes.

"Not enough free space for (file)" The drive holding the LU Engine folder is full. Free space, or move the folder to another drive under Settings, AI Backends, Model Storage.

"Below 7B: for local loading tests and experiments only. Not recommended for chat or agent work. Choose a model with at least 7B parameters." Not an error but a warning on small models. Chapter 3 explains why.

"Delete Model. Are you sure you want to delete (name)? This removes the model file from your disk and frees the space." The confirmation when you press "Delete" under Models, Installed. The engine is stopped first if that model is loaded.

ComfyUI errors the repair cannot fix

Most ComfyUI problems end with "Repair environment" under Settings, AI Backends, ComfyUI (Image & Video), and chapter 7 covers those. Two live outside the ComfyUI folder, and the app says so:

"A Microsoft Visual C++ runtime library is missing on this machine: VCOMP140.DLL. PyTorch loads it at import time and Windows does not install it on its own, so nothing pip does can fix this. Install the current Visual C++ Redistributable for x64 from https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist, restart Windows, then start ComfyUI again. Repair environment does not help here: the missing library belongs to Windows, not to the ComfyUI folder." Do what it says.

"PyTorch is on disk but its native libraries will not load on this machine. Two things cause that, in this order: the Microsoft Visual C++ Redistributable for x64 is missing or out of date (install the current one from https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist and restart Windows), or the GPU driver is older than the CUDA build that was installed (update the graphics driver). Do both, then start ComfyUI again. Repair environment does not help here: it rebuilds the folder, and both of these live outside it." Do both.

"This is a portable ComfyUI with its own bundled Python. Re-extract the portable package to repair it; the app cannot rebuild that environment." You pointed the app at a portable ComfyUI. Re-extract that package, or let the app install its own.

"Looks like the ComfyUI Desktop App binary folder ((path)). LU needs the ComfyUI Working Directory (with main.py, models/, custom_nodes/)" followed by where to find it (by default ~\Documents\ComfyUI, or the folder shown under the Desktop App's own settings as ComfyUI Working Directory). Paste that working directory into the Path field, not the program folder.

"The folder (path) has no requirements.txt, so it is not a complete ComfyUI checkout and its dependencies cannot be installed. Rename or delete that folder and run the install again." The path is not a ComfyUI. Fix the path or let the app install a fresh one.

"Remote ComfyUI" with the note to manage the Python process on the server itself. The Host field points at another machine, so Start, Stop and Repair are yours to do there.

Trainer errors

The Character Studio trainer (chapter 7) has its own environment and its own sentences. Every one of them ends with the fix and names the button to press afterwards, "Set up trainer in Character Studio".

"The drive holding the trainer folder ((path)) has N GB free and the trainer setup needs about 10 GB before anything is downloaded (PyTorch alone is 2.5 GB and installs with both copies on disk). Free up room on that drive, then press Set up trainer in Character Studio." Free the space.

"The download broke off during (step). Waiting 15 seconds and trying again (1 of 2)..." Not an error yet; the setup retries twice on a network failure.

"The trainer environment was built with Python (version), which the trainer cannot use (it needs 3.10, 3.11 or 3.12). Rebuilding it with Python (version), your training images and base models are left alone." The app fixes this by itself. Wait.

"The Python in the trainer environment is one the trainer cannot use (it needs 3.10, 3.11 or 3.12). Press Set up trainer in Character Studio: the setup looks for a matching Python on this machine on its own, installs 3.12 on Windows when there is none, and rebuilds the environment with it." Press the button.

"This PyTorch build has no kernels for your GPU (compute capability 12.x, the build stops at 9.x). An RTX 50 card on the old cu121 build does exactly this." The setup reinstalls PyTorch from the right channel on its own; if it says the automatic repair did not fix it, press "Set up trainer".

"This card has N GB of memory and the local training recipe needs 12 GB: it was proven on a 12 GB card with fp8 weights and block swapping, and below that the first training step runs out of memory after both cache steps. Character Studio in Cloud mode trains the same character without this limit." Use Cloud mode for training.

"Training a character needs a PyTorch build that can drive your AMD card, and pytorch.org publishes those for Linux only" (Windows with an AMD card, followed by the details). Local training needs an NVIDIA card or Linux with ROCm; Cloud mode trains the same character.

"AMD GPU detected, but no official ROCm wheel carries kernels for this card" (Linux, RX 5000 and most RX 6000 cards). Same answer: Cloud mode, or a card the ROCm wheels support.

"The Z-Image training base files are missing (z_image_bf16 / qwen_3_4b / ae). Get them from the Model Manager, then train again." Press "Download base files" in the Character Studio.

"Need at least 4 staged photos to train." Add photos.

"The trainer package (musubi_tuner) is not installed in the trainer environment." Press "Set up trainer".

"The installer was not allowed to write into the Python folder. Close every open Python, Jupyter or IDE debugger, and if that changes nothing, install Python for your own user instead of for all users, then press Set up trainer in Character Studio." Do what it says.

"This Python refuses installs outside a virtual environment and the venv module is missing. Install it from your package manager (python3-venv on Debian and Ubuntu, python-virtualenv on Arch, python3-virtualenv on Fedora), then press Set up trainer in Character Studio." (Linux) Install the package.

Linux notes

• The window stays black on some Wayland desktops: chapter 2 has the environment variables the app sets on a Wayland session and how to switch them off.
• "Open folder" buttons need xdg-utils installed; without it nothing opens.
• The AppImage clears PYTHONHOME and PYTHONPATH for the Python it starts, so a ComfyUI install from the AppImage works on a system Python.
• The engine needs libvulkan.so.1 and libgomp.so.1; the .deb and .rpm depend on them, the AppImage tells you if one is missing.
• An install a package manager owns (the AUR package, a hand unpacked .deb) updates itself into ~/.local/share/locally-uncensored/ as chapter 2 describes.
• Where the files live is in chapter 2.

Reset

At the bottom of every settings tab sit two buttons. "Reset General to defaults" (with the tab's name) puts that tab back; "Reset all settings" resets everything. Both need a second click: the button changes to "Click again to reset General" or "Click again to reset everything" and waits four seconds. The note under them reads "Personas, memories, conversations, workflows and MCP servers are kept." There is no button that deletes your chats or models; delete models under Models, Installed, and chats from their row in the sidebar, or remove the folders from chapter 2 after uninstalling.

Previous chapter: LU Cloud. Next chapter: FAQ and glossary. Back to the handbook overview.