Common Issues

Search Returns No Results

Symptoms: Searching your vault returns nothing, or the AI doesn’t seem to know about notes you’ve definitely created.

Solutions:

Check the index status in Settings > Search — look for the index entry count. If it shows 0 or nothing has been indexed, the vault may not have been indexed yet.
Click Re-index Vault in Settings to trigger a fresh index pass.
If re-indexing doesn’t help, use Clear Index and then Re-index Vault to start from scratch. This can take a few minutes for large vaults.
Make sure your vault path is set correctly in Settings > Vault. If NoteTalker is pointing at the wrong folder, it won’t find your notes.

App Won’t Start

Symptoms: NoteTalker crashes immediately, shows a blank window, or refuses to launch.

Solutions:

Windows: Try right-clicking the NoteTalker executable and choosing Run as administrator.
Windows: Check if antivirus software is quarantining or blocking NoteTalker. Add an exception for the NoteTalker installation folder.
macOS: If you see “NoteTalker can’t be opened because Apple can’t check it for malicious software” — right-click (or Control-click) the app and choose Open. Confirm in the dialog that appears. You only need to do this once.
Linux: Ensure the AppImage has execute permissions: chmod +x NoteTalker_x.x.x.AppImage
Try deleting the config file and relaunching (see FAQ for the path). This resets NoteTalker to a clean state — you’ll need to reconfigure your vault path.

Model Download Failed or Stuck

Symptoms: The first-launch model download never finishes, stalls at a percentage, or reports an error. Chat and voice stay unavailable because the models aren’t on disk yet.

Solutions:

Let it resume. Model downloads are resumable — reopen NoteTalker (or start the download again from Settings) and it picks up where it left off instead of starting over.
Check free disk space. The essential set is about 3 GB (the smallest model plus speech recognition and the voice); it’s about 8 GB with the default Mistral Nemo 12B model. Make sure the drive holding your NoteTalker app data has room to spare.
Check that Hugging Face is reachable. Models are fetched from huggingface.co. A corporate firewall, VPN, or content filter can block the download. Try again on an open network, or temporarily turn off the VPN, then reopen NoteTalker to resume.
The download happens once. After the models are on disk, NoteTalker runs fully offline — this network step is only needed the first time (and when you add another model).

GPU Not Detected

Symptoms: NoteTalker reports that no GPU was found, or the chat model refuses to load. The local language model needs a supported GPU to run.

Solutions:

Windows / Linux — NVIDIA GPU required. Install a current NVIDIA driver (525 or newer) and the CUDA 12.x runtime, then reboot and relaunch NoteTalker.
Linux — confirm the driver is loaded. Run nvidia-smi in a terminal; it should list your card. If it doesn’t, the driver isn’t installed or loaded correctly.
macOS — Apple Silicon required. The local model runs on Apple Silicon (M1 or later) using MLX/Metal. Intel Macs cannot run the chat model.
Free up the GPU. Close other GPU-heavy applications (games, other AI tools) that may be holding onto the GPU, then try again.

Out of VRAM or Model Won’t Load

Symptoms: An “out of memory” error when the model loads, or the model loads and then crashes partway through a reply.

Solutions:

Pick a smaller model in Settings > AI. The default Mistral Nemo 12B wants roughly 10–12 GB of VRAM. On an 8 GB card, switch to Qwen3 4B (~2.5 GB). On Apple Silicon, 16 GB of unified memory suits the 4B model and 24–32 GB suits the 12B.
Lower the context window size in Settings > AI. A larger context uses more VRAM (roughly 12 GB at 32K tokens, 17 GB at 64K with the 12B model). Dropping back toward the 8,192-token default frees memory.
Close other GPU applications so the model has the VRAM it needs to load.

Generation Is Slow

Symptoms: Replies take a long time to start, or text streams out slowly.

Solutions:

The first reply after a pause is slower. To free VRAM, NoteTalker unloads the model after about 10 minutes of inactivity and reloads it on your next message. That one-time reload adds a few seconds; later replies in the same session are quick.
Make sure the model fits your VRAM. A model too large for your GPU spills onto system memory and slows to a crawl — choose a model that fits your card (see Out of VRAM or Model Won’t Load above).
Confirm the GPU is being used. The chat model runs on your GPU (NVIDIA CUDA on Windows/Linux, MLX/Metal on Apple Silicon). If the GPU isn’t detected it can’t run at full speed — see GPU Not Detected above. Search and voice components fall back to the CPU when no accelerator is available, which is slower but still works.
Lower the context window size if you raised it — a larger context takes longer to process on every response.

License Activation Failed

Symptoms: Your key won’t activate, or you see “activated on a different device” or a message about a different major version.

Solutions:

Connect to the internet once. Activation is a one-time online step. After it succeeds, NoteTalker runs fully offline — you only need a connection for this first check.
“Activated on a different device.” A key covers 2 devices. If both slots are in use, open NoteTalker on the old machine and deactivate it to free a slot, then activate here. Reinstalling your OS or moving to new hardware looks like a new device, so deactivate the old slot first. If you can’t reach the old machine, contact support to clear a slot.
“For a different major version.” Your key entitles every 2.x release. Make sure you’re running a 2.x build — a key isn’t valid across a major-version change.
Copy the key exactly from your account dashboard at talkwithyournotes.com, with no extra spaces, and paste it into Settings > License & About.

See License & Activation for the full activation and device-management walkthrough.

Voice Not Working

Symptoms: Voice input does nothing, TTS doesn’t play, or “FFmpeg not found” appears in Voice settings.

Solutions:

Check FFmpeg status in Settings > Voice. FFmpeg is required for audio processing.
- Windows: Download from ffmpeg.org and add it to your PATH
- macOS: Run brew install ffmpeg in Terminal
- Linux: Run sudo apt install ffmpeg (Debian/Ubuntu) or your distro’s equivalent After installing, restart NoteTalker and check the status again.
Grant microphone permissions — your OS may be blocking NoteTalker from accessing the microphone. Check:
- Windows: Settings > Privacy & Security > Microphone
- macOS: System Preferences > Security & Privacy > Privacy > Microphone
- Linux: Check PulseAudio or PipeWire permissions
Confirm the voice models downloaded. Speech recognition (Whisper Base) and the voice (Kokoro) download on first launch and run entirely on your device. If that download was interrupted, voice won’t work until it finishes — check the model download status in Settings > Voice and re-run it if needed.

Voice Sounds Robotic

Symptoms: Spoken replies mispronounce names or unusual words, or the voice sounds flat and mechanical.

Solutions:

Install espeak-ng. NoteTalker’s on-device voice (Kokoro) uses espeak-ng to sound out words it doesn’t already know. Without it, NoteTalker falls back to a built-in pronunciation dictionary and can mangle unfamiliar names and terms. Install it from Settings > Voice (guided install), or with your package manager — sudo apt install espeak-ng (Linux), brew install espeak-ng (macOS). Restart NoteTalker afterward.
Adjust the speaking speed in Settings > Voice if playback feels too fast or too slow.

Slow Performance with Large Vaults

Symptoms: NoteTalker feels sluggish, especially after opening or when chatting. High RAM or CPU usage.

Solutions:

Use the bundled BGE-small embedding model in Settings > Search > Embedding Model. BGE-small ships inside NoteTalker and uses less memory; BGE-base is an optional ~436 MB download that’s more accurate but heavier. Whichever you pick, switching rebuilds the search index, which can take a few minutes on a large vault.
Increase the embedding idle timeout in Settings > Search. Setting this to 20–30 minutes keeps the model loaded when you’re using NoteTalker actively, but frees memory faster when you step away.
Check your vault size — very large vaults (10,000+ files) can slow initial indexing. Exclude folders you don’t need indexed using the vault exclusion settings.

Context Indicator Showing Red

Symptoms: The context usage indicator in the chat header turns red or orange.

What it means: Your current conversation is long and approaching the AI’s context window limit.

Solutions:

Start a new session — click New Chat to reset the conversation. Important facts from your current session will be saved to long-term memory before clearing.
Let NoteTalker auto-compact — if you continue the conversation, NoteTalker will automatically summarize older messages to free up space. Important information won’t be lost.
If you consistently hit the context limit, try shortening your identity and memory files (persona, user profile, rules) in Settings > AI & Voice. Shorter files mean more room for conversation.

Didn’t find a solution here? See Contact & Support.