Troubleshooting

Run the basic diagnostic sequence

Goal

Identify the failing layer before changing or deleting data.

Before you start

Do not use Reset All as a first troubleshooting step. Preserve the exact error message and create a backup before destructive action.

Steps

1. Confirm the version under Settings → About.
2. Restart Local Waifu and reproduce the issue once.
3. On Windows, run Settings → Hardware → Runtime status → Check.
4. Check the active chat, memory, image, speech, and voice models relevant to the failure.
5. Check Settings → Hardware → Network, especially Offline Mode, Use System Proxy, and Ollama Host.
6. Check free disk space and available RAM/VRAM.
7. Open Settings → Advanced → App Logs.
8. If support is needed, save and review a Diagnostics report before sending it.

Expected result

The problem is narrowed to installation, model/runtime, resource pressure, network routing, permissions, Telegram pairing, license, update, or data health.

If something goes wrong

Stop before reset or manual file replacement. Preserve the data directory and backup, record the last successful action, and contact support.

Installation and launch

Symptom	Likely cause	What to do
macOS blocks the first launch	Gatekeeper verification or an unrecognized download	Confirm the installer came from the official source. In Finder, Control-click Local Waifu, choose Open, and approve the system prompt if macOS offers it. Do not routinely disable Gatekeeper or strip quarantine attributes.
Windows shows SmartScreen	The installer may not have paid Authenticode reputation	Confirm the file came from the official source, inspect the publisher/source, select More info, then Run anyway only if you trust the file.
Windows app does not open or shows a blank window	Missing/damaged WebView2, antivirus interference, or incomplete install	Reboot, install/repair Microsoft Edge WebView2 Runtime, allow the official app in security software, and reinstall.
Installer appears stuck	Antivirus scanning, low disk space, or running app processes	Wait for scanning, verify free space, quit Local Waifu and its local engine, then retry.

Chat models, downloads, and memory

Symptom	Likely cause	What to do
Model download will not start or stalls	Engine startup, network, proxy/VPN, registry access, or disk space	Check Use System Proxy, VPN/firewall, free space, and internet access. Restart the app, then retry in Settings → Models.
Hugging Face repo has no installable quant	It contains sharded GGUF files or no GGUF	Choose a repository with a single runnable .gguf quant. Sharded GGUF and SafeTensors are not installed through the chat-model search panel.
Chat shows offline or no reply	Local engine/model unavailable, bad Ollama Host, cloud blocked, or missing provider credentials	Run Runtime status, check the active chat model, reset Ollama Host, disable Offline Mode only for intentional cloud use, and verify the provider account/key.
Clicking Stop ends the visible stream but CPU/GPU stays busy	Stop releases the UI while the backend may finish the current generation	Wait for the current generation to settle before starting resource-intensive work.
Replies are very slow or the app runs out of memory	Model or context is too large; GPU placement is partial/CPU	Reduce Context Window, choose a smaller quantized model, turn off Deeper thinking, and check GPU placement on Windows.
Memory recall is weaker after changing the embedding model	Re-embedding is still in progress	Keep the required memory model installed and allow continued use to rebuild embeddings. Keyword-only recall may be used temporarily.

Images and local image models

Symptom	Likely cause	What to do
Image cannot be attached	File is not an image, exceeds 5 MB, another image is pending, or vision is unavailable	Use one valid image under 5 MB and verify Sees images or a vision-capable model/provider.
Custom checkpoint import fails	Wrong format, too small, invalid SafeTensors, or not SDXL	Use one regular .safetensors SDXL checkpoint of at least 512 MiB. .ckpt is not supported by the 1.7.3 importer.
Imported LoRA cannot be enabled	Active model is not SDXL, family is unknown, or three LoRAs are already active	Select an SDXL base model, use a verified SDXL LoRA, and keep at most three active. Confirm compatibility with a test render.
SDXL imports but will not run	Insufficient RAM or disk/runtime resources	Custom SDXL uses a 16 GiB RAM profile. Close other apps or use a lighter image model.
Image model cannot be deleted	Rendering or download is active	Wait for the operation to finish, then retry.

Voice, microphone, and calls

Symptom	Likely cause	What to do
A call cannot start	Speech recognition is missing or unavailable	Install/configure Whisper or a supported cloud STT route. STT is required for a full call.
No spoken reply	Voice model is missing or unavailable	Install Supertonic or configure a supported cloud TTS route. A fallback may be used, but quality can be lower.
Speech has the wrong accent or language	Wrong language, English fallback, or mismatched custom sample	Select the correct language and voice model. For a custom voice, use 10 to 30 seconds of clean speech in the target language.
Microphone is silent	OS permission denied or wrong input device	Grant microphone permission in the operating system and select/test the correct input device. Restart afterward.
Dictation stops unexpectedly	Ten-minute limit or disconnected microphone	Start another dictation session and reconnect or reselect the microphone.

Telegram

Symptom	Likely cause	What to do
Test succeeds but bot does not answer	Bot was not started	Select Start. Testing does not save or start the token.
Bot will not pair with a new account	It is pinned to the first chat	Use Forget token + pin, restart the bot, and message it first from the correct account.
Voice only returns text	Voice model is not ready	Install/configure the voice model. Text is the intentional fallback.
Telegram model change also changes desktop	Shared active-model setting	This is expected. Select the preferred model again from either interface.

License and updates

Symptom	Likely cause	What to do
Direct key is rejected	Typo, no network for activation, invalid key, or device limit	Paste the exact key, reconnect, and retry. Deactivate an old device or contact support if the device limit is reached.
Trial expired	Direct-edition trial period ended	Activate a valid lifetime key. User data is retained; do not reset in an attempt to obtain a new trial.
License tab is absent	Store/Unlocked edition	This is expected; that edition does not require a key.
Update control is absent	Store/Unlocked edition	Update through the store/client used to obtain the app. Do not mix it with the Direct updater.
Install & Restart is blocked	Data-health or encryption-metadata check failed	Create a backup and contact support. Do not force file replacement.

Backup, export, and data recovery

Symptom	Likely cause	What to do
Backup destination is rejected	It overlaps the live Local Waifu data directory	Choose an external folder or another location outside the app data tree.
Conversation JSON does not restore the app	It is an export, not a backup	Use character export/import for self-service transfer. Preserve the full backup for support-assisted recovery.
There is no Restore backup button	Version 1.7.3 has no complete Restore UI	Quit the app, preserve the backup unchanged, and request a support procedure. Never merge it into the live directory while the app is running.
Reset did not remove license, cloud keys, or Telegram token	Reset does not clear the secret store	Remove provider credentials explicitly, use Forget token + pin, and delete the remaining data directory only for a deliberate full wipe.

---