Troubleshooting
Fix common problems with models, voice, images, Telegram, and startup.
Follow the bold button names and numbered steps. Technical names are included only when you need to recognize a model or file inside the app.
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
- Confirm the version under Settings → About.
- Restart Local Waifu and reproduce the issue once.
- Run Settings → Performance → Runtime status → Check.
- Check the active chat, memory, image, speech, and voice models relevant to the failure.
- Check Settings → Performance → Network, especially Offline Mode, Use System Proxy, and Ollama Host.
- Check free disk space and available RAM/VRAM.
- Open Settings → Advanced → Developer Options and, under App Logs, select Open Logs.
- If support is needed, save and review a Diagnostics report before sending it. It is on the same Developer Options section.
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.
The app will not open
| Symptom | Likely cause | What to do |
|---|---|---|
| A screen says Local Waifu could not open your database. | The database or an encryption piece could not be read | Nothing was changed. Use Save a copy of everything and read Chapter 47 before anything else |
| A screen says Local Waifu could not check its data. | A temporary failure while checking | Select Try again or Reload window |
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. |
| Chat says the local model failed but a reply still arrived from a cloud provider | Use the cloud when the local model can’t answer is on | Turn it off in Settings → Performance → Network if you do not want any reply to leave your computer. It is off by default. |
| 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.8.0 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, or an invalid key | Paste the exact key, reconnect, and retry. There is no device limit. If the app says the license could not be activated on this device, write to support. |
| 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. |
3D avatar, desktop pet, and screen awareness
| Symptom | Likely cause | What to do |
|---|---|---|
| The portrait shows instead of the 3D model | The model could not load, or 3D avatar is off | Open Settings → 3D Avatar, turn on 3D avatar, and pick another model. A model that fails in the preview cannot be used |
| A model imports but her lips do not move | The model has no mouth shapes | Use a model that has them. It still blinks and smiles |
| A face does not match her feeling | Automatic expression matching missed it | Open Expression mapping and choose the model’s own expression for that feeling |
| Textures are missing on an MMD model | The bare .pmx was imported | Import the .zip the model came in |
| Desktop mode shows a card instead of her | The 3D avatar is off or her model is not ready | Turn it on and pick a model in Settings → 3D Avatar, then try again |
| The desktop shortcut does nothing | Another app owns the chord, or the avatar is off | Check the system keyboard shortcuts, or use Put her on the desktop in the sidebar |
| She stays still on the desktop | Quiet Mode is on | She stays put while a fullscreen app, a meeting, or a locked screen is active |
| A selfie ignores the 3D model | Her 3D model is not on screen, or the image model cannot take a reference | Use local FLUX.2, Google, or OpenAI as the image model, or accept the portrait |
| Make it a real photo is unavailable | The image model cannot take a reference picture, Offline Mode is on, or no active license | Pick FLUX.2 klein in Settings → Models → Image Models |
| Screen awareness cannot see | Missing Screen Recording permission (macOS), no vision model, or the app is on the protected list | Allow Screen Recording, relaunch, set up a vision model, and check Never capture these apps |
Routines, voice features, and groups
| Symptom | Likely cause | What to do |
|---|---|---|
| A routine did nothing | Its switch is off, Offline Mode is on, or she was quiet or you were typing | Check the switch and Last run, and turn off Offline Mode. It retries on its own when quiet |
| Reminder follow-up is missing | It exists only on macOS | Use another routine on Windows |
| Morning brief has no weather | No city set | Enter a City and select Find |
| A voice message is not sent | It was too short, over two minutes, or a reply was still coming in | Hold the button while you talk, and try again when she finishes |
| Hands-free does not start | The microphone is busy, the wake phrase is too short, or the wake-word model is missing | Check the status under Hands-free and the message shown |
| A song or story will not start | No fal.ai key (songs), Offline Mode (songs), a call is open, or no active license | Follow the message the app shows. Songs need a fal.ai key under Settings → Models → Image Models |
| In a group, the wrong character answers | The default rules chose someone else | Start the message with her name, or say a word that addresses everyone |
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 button that restores a backup over my data | 1.8.0 only offers Restore a backup, which checks a backup by copying it into a new folder | Use it to confirm the backup is usable. Quit the app, preserve the backup unchanged, and request a support procedure for a full restore. 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. |