Documentation›Integrations, data, and support
42 Data and support

Troubleshooting

Fix common problems with models, voice, images, Telegram, and startup.

Local Waifu 1.8.0 macOS Windows
plain English first

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

  1. Confirm the version under Settings → About.
  2. Restart Local Waifu and reproduce the issue once.
  3. Run Settings → Performance → Runtime status → Check.
  4. Check the active chat, memory, image, speech, and voice models relevant to the failure.
  5. Check Settings → Performance → Network, especially Offline Mode, Use System Proxy, and Ollama Host.
  6. Check free disk space and available RAM/VRAM.
  7. Open Settings → Advanced → Developer Options and, under App Logs, select Open Logs.
  8. 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

SymptomLikely causeWhat to do
A screen says Local Waifu could not open your database.The database or an encryption piece could not be readNothing 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 checkingSelect Try again or Reload window

Installation and launch

SymptomLikely causeWhat to do
macOS blocks the first launchGatekeeper verification or an unrecognized downloadConfirm 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 SmartScreenThe installer may not have paid Authenticode reputationConfirm 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 windowMissing/damaged WebView2, antivirus interference, or incomplete installReboot, install/repair Microsoft Edge WebView2 Runtime, allow the official app in security software, and reinstall.
Installer appears stuckAntivirus scanning, low disk space, or running app processesWait for scanning, verify free space, quit Local Waifu and its local engine, then retry.

Chat models, downloads, and memory

SymptomLikely causeWhat to do
Model download will not start or stallsEngine startup, network, proxy/VPN, registry access, or disk spaceCheck Use System Proxy, VPN/firewall, free space, and internet access. Restart the app, then retry in Settings → Models.
Hugging Face repo has no installable quantIt contains sharded GGUF files or no GGUFChoose 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 replyLocal engine/model unavailable, bad Ollama Host, cloud blocked, or missing provider credentialsRun 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 providerUse the cloud when the local model can’t answer is onTurn 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 memoryModel or context is too large; GPU placement is partial/CPUReduce 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 modelRe-embedding is still in progressKeep the required memory model installed and allow continued use to rebuild embeddings. Keyword-only recall may be used temporarily.

Images and local image models

SymptomLikely causeWhat to do
Image cannot be attachedFile is not an image, exceeds 5 MB, another image is pending, or vision is unavailableUse one valid image under 5 MB and verify Sees images or a vision-capable model/provider.
Custom checkpoint import failsWrong format, too small, invalid SafeTensors, or not SDXLUse one regular .safetensors SDXL checkpoint of at least 512 MiB. .ckpt is not supported by the 1.8.0 importer.
Imported LoRA cannot be enabledActive model is not SDXL, family is unknown, or three LoRAs are already activeSelect 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 runInsufficient RAM or disk/runtime resourcesCustom SDXL uses a 16 GiB RAM profile. Close other apps or use a lighter image model.
Image model cannot be deletedRendering or download is activeWait for the operation to finish, then retry.

Voice, microphone, and calls

SymptomLikely causeWhat to do
A call cannot startSpeech recognition is missing or unavailableInstall/configure Whisper or a supported cloud STT route. STT is required for a full call.
No spoken replyVoice model is missing or unavailableInstall Supertonic or configure a supported cloud TTS route. A fallback may be used, but quality can be lower.
Speech has the wrong accent or languageWrong language, English fallback, or mismatched custom sampleSelect the correct language and voice model. For a custom voice, use 10 to 30 seconds of clean speech in the target language.
Microphone is silentOS permission denied or wrong input deviceGrant microphone permission in the operating system and select/test the correct input device. Restart afterward.
Dictation stops unexpectedlyTen-minute limit or disconnected microphoneStart another dictation session and reconnect or reselect the microphone.

Telegram

SymptomLikely causeWhat to do
Test succeeds but bot does not answerBot was not startedSelect Start. Testing does not save or start the token.
Bot will not pair with a new accountIt is pinned to the first chatUse Forget token + pin, restart the bot, and message it first from the correct account.
Voice only returns textVoice model is not readyInstall/configure the voice model. Text is the intentional fallback.
Telegram model change also changes desktopShared active-model settingThis is expected. Select the preferred model again from either interface.

License and updates

SymptomLikely causeWhat to do
Direct key is rejectedTypo, no network for activation, or an invalid keyPaste 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 expiredDirect-edition trial period endedActivate a valid lifetime key. User data is retained; do not reset in an attempt to obtain a new trial.
License tab is absentStore/Unlocked editionThis is expected; that edition does not require a key.
Update control is absentStore/Unlocked editionUpdate through the store/client used to obtain the app. Do not mix it with the Direct updater.
Install & Restart is blockedData-health or encryption-metadata check failedCreate a backup and contact support. Do not force file replacement.

3D avatar, desktop pet, and screen awareness

SymptomLikely causeWhat to do
The portrait shows instead of the 3D modelThe model could not load, or 3D avatar is offOpen 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 moveThe model has no mouth shapesUse a model that has them. It still blinks and smiles
A face does not match her feelingAutomatic expression matching missed itOpen Expression mapping and choose the model’s own expression for that feeling
Textures are missing on an MMD modelThe bare .pmx was importedImport the .zip the model came in
Desktop mode shows a card instead of herThe 3D avatar is off or her model is not readyTurn it on and pick a model in Settings → 3D Avatar, then try again
The desktop shortcut does nothingAnother app owns the chord, or the avatar is offCheck the system keyboard shortcuts, or use Put her on the desktop in the sidebar
She stays still on the desktopQuiet Mode is onShe stays put while a fullscreen app, a meeting, or a locked screen is active
A selfie ignores the 3D modelHer 3D model is not on screen, or the image model cannot take a referenceUse local FLUX.2, Google, or OpenAI as the image model, or accept the portrait
Make it a real photo is unavailableThe image model cannot take a reference picture, Offline Mode is on, or no active licensePick FLUX.2 klein in Settings → Models → Image Models
Screen awareness cannot seeMissing Screen Recording permission (macOS), no vision model, or the app is on the protected listAllow Screen Recording, relaunch, set up a vision model, and check Never capture these apps

Routines, voice features, and groups

SymptomLikely causeWhat to do
A routine did nothingIts switch is off, Offline Mode is on, or she was quiet or you were typingCheck the switch and Last run, and turn off Offline Mode. It retries on its own when quiet
Reminder follow-up is missingIt exists only on macOSUse another routine on Windows
Morning brief has no weatherNo city setEnter a City and select Find
A voice message is not sentIt was too short, over two minutes, or a reply was still coming inHold the button while you talk, and try again when she finishes
Hands-free does not startThe microphone is busy, the wake phrase is too short, or the wake-word model is missingCheck the status under Hands-free and the message shown
A song or story will not startNo fal.ai key (songs), Offline Mode (songs), a call is open, or no active licenseFollow the message the app shows. Songs need a fal.ai key under Settings → Models → Image Models
In a group, the wrong character answersThe default rules chose someone elseStart the message with her name, or say a word that addresses everyone

Backup, export, and data recovery

SymptomLikely causeWhat to do
Backup destination is rejectedIt overlaps the live Local Waifu data directoryChoose an external folder or another location outside the app data tree.
Conversation JSON does not restore the appIt is an export, not a backupUse 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 data1.8.0 only offers Restore a backup, which checks a backup by copying it into a new folderUse 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 tokenReset does not clear the secret storeRemove provider credentials explicitly, use Forget token + pin, and delete the remaining data directory only for a deliberate full wipe.