Troubleshooting

Every failure mode below has been hit by a real alpha tester. Each entry lists the symptom (what you see), the cause (what's actually happening), and a fix per OS. If you run into something that isn't here, use Discord Support or open a ticket; we'd rather expand this page than make you guess.

For first-install steps and the dictation loop itself, see Install and First dictation. For what Quill does and doesn't send off your machine, see the Privacy promise.

Quick index

• Setup: permissions, model download, polish endpoint, hotkey, Wayland
• Runtime: crashes, latency, stuck modifier keys, lost settings, orphan processes
• Linux-specific: engine-not-found, .deb vs .rpm, AppImage FUSE, build-from-source dev libs
• Intel Mac: unsupported in the current closed alpha
• Audio: wrong input device, intermittent cut-out

Setup

Microphone permission denied

Symptom: the level meter on the setup screen is flat. The Activity log shows no captures. The setup screen reads "Microphone permission: Denied," or the daemon logs audio: failed to open input stream: permission denied.

Cause: the OS hasn't granted your user (or the Quill process specifically) access to the microphone device.

Accessibility permission denied (macOS)

Symptom: Quill transcribes correctly (you can see the polished text in the Activity log) but nothing gets typed into the focused field. Or text appears via a momentary clipboard paste that briefly clobbers whatever you'd previously copied.

Cause: the Accessibility inject mode writes directly to the focused UI element's kAXSelectedText and needs the macOS Accessibility permission. Starting in alpha.4, Quill no longer hard-bails when the permission is missing (it degrades gracefully to clipboard paste) but the Accessibility path is the high-quality one and worth granting.

Whisper model not found / download failed

Symptom: the setup screen sits at "Downloading speech model… 0%" indefinitely, or jumps to "Download failed: connection reset." The daemon logs stt: model file missing at <path>.

Cause: the first-run downloader (a single HTTPS GET to the whisper.cpp ggml mirror) was blocked, interrupted, or failed. The download is not partial-resume; a 99% failure restarts from scratch.

The download URLs come from the whisper.cpp project's public release manifest. Quill verifies size after download but does not yet verify SHA; a manual download from a trusted mirror is fine.

Polish model download or enhance failed

Symptom: captures work, the raw Whisper transcript shows up in the Activity log, then a polish failed: connection refused warning, and the raw transcript is injected instead of the polished version. Subsequent captures show the same error.

Cause: the embedded GGUF model is missing, still downloading, failed SHA verification, or the optional system / remote Ollama-compatible endpoint is unreachable. Release packages no longer ship a bundled Ollama binary.

Triage (any OS):

# Is the embedded GGUF present in Quill's model cache?
ls -lh ~/Library/Caches/quill/models 2>/dev/null || ls -lh ~/.cache/quill/models

# If you opted into system/remote polish, is that endpoint reachable?
curl -s http://127.0.0.1:11434/api/tags

The daemon logs the concrete model-download, SHA, or endpoint error when polish fails. See Where are the logs? below.

Hotkey doesn't trigger

Symptom: F8 (or whatever key you set) does nothing: no capture starts. Or F8 toggles Music play/pause / iTunes media controls instead of starting a capture.

Cause: another app, the OS itself, or your desktop environment grabbed the key first. The OS-level grab wins; Quill never sees the event.

Wayland injection doesn't work

Symptom: on a Wayland session (Hyprland, Sway, GNOME-Wayland, KDE Plasma 6 Wayland), the global hotkey is never delivered to the daemon, or nothing gets injected even when capture works. Capture itself may also be silent if you're using a compositor that grabs /dev/input/* exclusively.

Cause: Wayland's security model intentionally blocks normal user processes from grabbing global keys or synthesizing input events outside their own surfaces. This is by design, not a bug; we work around it via compositor binds and XWayland fallback.

Known limitation: even with the compositor binding, native Wayland applications using wl_keyboard directly may reject synthesized events. Quill's injection currently falls back to XWayland, which works for any app running under XWayland (basically every non-GTK4-native app today) but not for true Wayland-only surfaces.

Runtime

Daemon crashed during dictation

Symptom: mid-dictation the menu-bar icon goes from red back to grey, the GUI shows "Quill stopped unexpectedly," and no transcript appears. Subsequent F8 presses do nothing until you click Restart Quill in the GUI.

Cause: an unhandled error in the daemon process. Could be Whisper inference (model file corrupted on disk), the audio capture thread (device disconnected mid-capture, common with USB mics), or the polish subprocess.

First step on every OS: capture the daemon log before anything else. See Where are the logs?. Then:

When filing the bug, include: OS version (sw_vers on macOS, lsb_release -a on Linux), Quill version (quill-daemon --version), and whether the crash reproduces with Polish backend = None (helps isolate whether it's the polish pass or the pipeline itself).

Polish takes forever / times out

Symptom: capture finishes (release F8, see the red icon go away), the raw transcript appears in the Activity log, then a long pause (10 s, 20 s, 60 s) before the polished version appears or the daemon logs polish stage exceeded 5s soft timeout (added in alpha.4).

Cause: either the local model is slow on your hardware, the model is loaded fresh (first-call latency is always higher than steady-state), or you've pointed polish_backend = "remote" at a network endpoint that's slow or unreachable.

Cmd+V got stuck after Quill ran

Symptom: after a Quill capture that used the Paste inject mode, your keyboard is stuck: typing a produces select-all, typing s saves, etc. The Cmd (macOS) or Ctrl (Linux) modifier appears to be held down even though nothing is physically pressed.

Cause: a bug in alpha.3 and earlier: the Paste inject path's Cmd+V Click step could error and never reach the modifier Release, leaving the modifier "stuck" until the user pressed it manually.

Status: Fixed in alpha.4 by #78. The modifier-key release is now guaranteed: an explicit Release runs after Click even when Click itself errors.

If you're already on alpha.4 or newer and you still see a stuck modifier, that's a regression: file a bug and include the inject mode you were on (accessibility / keystroke / paste).

My settings reset themselves

Symptom: every time you launch Quill, your hotkey choice, polish backend, inject mode, and other Settings reset to defaults. Or the settings persist for a while, then one launch they're all gone.

Cause: a bug in alpha.3 and earlier: quill-app wrote settings non-atomically (write-in-place), so a crash mid-write left a half-written TOML file that the next launch parsed as defaults, silently wiping every preference.

Status: Fixed in alpha.4 by #81. Settings are now written atomically (temp file → fsync → rename), so a crash mid-write can't corrupt the file. A schema_version field was added for future migrations, and a warn-log fires on TOML parse failure so silent resets are visible in the daemon log.

Clipboard contents disappeared

Symptom: you had something on your clipboard (a copied URL, a chunk of code), you triggered a Quill dictation, the inject completed, and your clipboard now contains the dictated text instead of your original copy.

Cause: a bug in alpha.3 and earlier: the Paste inject path's stash-set-paste-restore sequence used ? after set_text, so any failure in the Paste step dropped your prior clipboard before the restore block ran. Even the success path occasionally raced.

Status: Fixed in alpha.4 by #78. Stash → set → paste → restore is now a four-phase guarded sequence with the restore unconditional once the stash succeeded. Clipboard contents are guaranteed to round-trip.

Daemon or legacy polish subprocess orphaned after Quill closed

Symptom (pre-alpha.4): you close the Quill window, but ps aux | grep -E 'quill|ollama' shows quill-daemon and, on legacy development builds, ollama serve still running. They hold the microphone, keep the polish model in RAM, and don't exit until you reboot or pkill -9 them.

Cause: two distinct shutdown paths could leak. The GUI's Drop impl called try_lock() on a mutex permanently held by the daemon-waiter task, so start_kill never ran (the daemon outlived the GUI). Separately, the daemon's IPC Shutdown watchdog called process::exit(0) without first signaling the legacy bundled-Ollama PID (so Ollama outlived the daemon).

Status: Fixed in alpha.4 by #74 (GUI → daemon) and #79 (daemon → legacy polish child). The GUI now captures the daemon's PID at spawn time and signals SIGTERM (SIGKILL after 100 ms) directly via libc::kill, bypassing the mutex. The daemon's IPC watchdog now signals any legacy bundled-Ollama PID before exiting.

If you're already on alpha.4 or newer and you still see an orphan, include the ps output in your bug report along with the OS version.

Where are the logs?

The Quill GUI has an Activity log panel; toggle it from the menu bar. That covers transcripts, pipeline events, and recoverable warnings.

For lower-level daemon logs (panics, Ollama subprocess output, IPC events), launch the daemon manually with stderr attached:

By default, raw transcripts are not printed to stdout; that's a deliberate privacy choice as of alpha.4 (see the Privacy promise). To see them for debugging, pass --emit-transcripts or set QUILL_EMIT_TRANSCRIPTS=1. The GUI sets this env var when it spawns the daemon child, so the Activity log panel keeps working; CLI users get the privacy default.

Linux-specific

"Couldn't find the Quill engine"

Symptom: Quill opens but the setup screen reads "Couldn't start the Quill engine." The Activity log is empty. The GUI process is alive but no daemon spawns.

Cause: a bug in alpha.3 and earlier: the .deb / AppImage installer puts quill-daemon at /usr/libexec/quill/quill-daemon, but the GUI's binary resolver only checked the sibling of quill-app. Launch failed with couldn't find the Quill engine.

Status: Fixed in alpha.4 by #68. The resolver now also walks ../libexec/quill/ in addition to the sibling-of-quill-app path.

.deb won't install on Fedora / RHEL / other RPM distros

Symptom: running rpm -i quill_*.deb or dnf install ./quill_*.deb errors out. Or dpkg isn't installed in the first place.

Cause: .deb packages don't install on RPM distros: different package format. There's no .rpm yet.

Fix: use the AppImage:

chmod +x Quill-*-x86_64.AppImage
./Quill-*-x86_64.AppImage

The AppImage uses embedded llama.cpp for polish and downloads the verified GGUF into Quill's model cache on first setup. It works on bare Fedora / RHEL / openSUSE / Arch without an Ollama install, except for fuse2, which is an AppImage runtime requirement (see the next entry).

AppImage won't start: "FUSE error"

Symptom: running the AppImage fails with fuse: failed to exec fusermount: No such file or directory, or dlopen(): error loading libfuse.so.2, or just a silent exit.

Cause: AppImage runtime needs fuse2 (libfuse.so.2) to mount the bundle. Modern distros default to fuse3, which is not backward-compatible. Until the AppImage build switches to a static runtime (planned), fuse2 is required.

Missing X11 dev libs at build time

Symptom: cargo build fails with errors like X11/extensions/XInput2.h: No such file or directory, Package xtst was not found in the pkg-config search path, or ld: cannot find -lXi.

Cause: Quill links against XInput2 and XTest at build time for the keystroke-injection path. The runtime shared libraries are usually already installed; the development headers (the *-devel or *-dev packages) are not.

After installing, cargo clean && cargo build --release --workspace should succeed. If you're cross-compiling, the dev headers must come from your target sysroot, not your host.

If llama-cpp-sys-2 fails during bindgen with fatal error: 'stdbool.h' file not found, clang's resource headers are not visible to bindgen. Install clang / libclang-dev, then rerun the build; the Linux packaging script also exports BINDGEN_EXTRA_CLANG_ARGS from clang -print-resource-dir when clang is available and always adds cc -print-file-name=include when that directory exists. Minimal self-hosted runners may omit the clang executable, but they still need the libclang shared library that bindgen loads. The package script checks common Debian and RPM library paths, including /usr/lib64.

If whisper-rs fails with errors like no field greedy on type whisper_full_params, no field beam_search, or no field n_threads, the local bindgen output for whisper.cpp is wrong for the whisper-rs crate version. Quill's repo-level Cargo config sets WHISPER_DONT_GENERATE_BINDINGS=1 so source builds use the pre-generated bindings shipped by whisper-rs-sys, matching release CI. If you build from a copied source tree that omits .cargo/config.toml, set the variable manually before building:

WHISPER_DONT_GENERATE_BINDINGS=1 cargo build --release --workspace

whisper-rs-sys checks whether the variable is present, not whether it is truthy. Setting WHISPER_DONT_GENERATE_BINDINGS=0 still disables local binding generation; remove or comment out the variable if you intentionally need to run bindgen yourself.

Linux package starts with "libllama.so: cannot open shared object file"

Symptom: launching quill-app or the AppImage exits immediately with error while loading shared libraries: libllama.so.

Cause: Linux release packages link embedded llama.cpp dynamically so it can coexist with whisper.cpp in the same app and daemon binaries. The package should include those llama.cpp shared libraries under /usr/lib/quill for .deb, or usr/lib/quill inside the AppImage.

Fix: re-download the release asset. If it still happens, attach the output of dpkg-deb --contents quill_*_amd64.deb | grep usr/lib/quill for .deb, or ./Quill-*.AppImage --appimage-extract followed by find squashfs-root/usr/lib/quill -maxdepth 1 -type f -print for AppImage installs.

Intel Mac

Quill is unsupported on Intel Macs

Symptom: double-clicking the app icon does nothing, or macOS says "You can't open the application Quill because it is not supported on this type of Mac." Running the app binary from Terminal may show Bad CPU type in executable.

Cause: current closed-alpha macOS packages are Apple Silicon-only. The .dmg ships aarch64-apple-darwin binaries for M-series Macs; it is not a universal Mach-O build and does not include x86_64 macOS binaries.

Fix: use an Apple Silicon Mac for the macOS alpha, or use the Linux x86_64 .AppImage / .deb artifact on a supported Linux machine. Intel macOS builds are not part of the closed-alpha release lane.

Audio

Wrong microphone selected / picks the wrong input device

Symptom: the level meter is flat (or shows your speakers, oddly), the transcript is empty or full of background noise, and you have multiple input devices on your machine (built-in mic + USB headset + HDMI capture card, say).

Cause: Quill defaults to whatever your OS reports as the "default input device." Sometimes that's not the device you actually speak into: a Blue Yeti might rank below a HDMI capture-card mic Quill has no way to know about.

Fix: list devices, then pin Quill to the right one.

# List input devices the daemon can see
quill-daemon devices

The output looks like:

default input: Built-in Microphone

all input devices:
  [0] Built-in Microphone: 48000 Hz, 1 ch, F32
  [1] Blue Yeti: 48000 Hz, 2 ch, F32
  [2] HDMI Audio Capture: 48000 Hz, 2 ch, F32

Then either:

On Linux, alpha.4 also auto-prefers PipeWire then PulseAudio over ALSA when multiple backends are present, fixing the common "ALSA picked a phantom HDMI input" case (#25). If you're on alpha.3 or earlier and stuck on the wrong backend, upgrade.

Intermittent silence / cut-out mid-sentence

Symptom: the transcript captures the start of what you said, then nothing, then maybe the tail end. Or whole sentences come back as empty. The Activity log shows captures completing in normal duration but with very short transcripts.

Cause: the voice-activity detector (VAD) ended the capture prematurely. Defaults assume a "natural pause" of 2 s ends a phrase; if you speak slowly, take long breaths, or have background noise dipping under the VAD floor, captures truncate. Conversely, constant background noise (fan, fridge, traffic) can keep the VAD "on" past your actual speech and pad the capture with seconds of silence Whisper transcribes as (silence) / nothing.

Fix: tune the VAD silence threshold.

If background noise is the issue, the right fix is hardware: a directional mic, a noise-gate plugin, or moving away from the noise. Software denoising in the capture path is on the roadmap but not in alpha.

Still stuck?

Open a Discord Support ticket. Include:

• Your OS + version (sw_vers on macOS, lsb_release -a on Linux).
• Your Quill version (quill-daemon --version).
• The daemon log captured with stderr attached, if you can reproduce (see Where are the logs?).
• Whether the bug reproduces with Polish backend = None (helps isolate whether it's a polish-pass issue or a pipeline issue).

This page is updated every release. Cross-reference the CHANGELOG for the canonical record of what's been fixed when.