Troubleshooting

🌐 Language: English | Français

Troubleshooting

Common issues, their symptoms, and fixes — organized by category. If your problem isn't listed here, check FAQ or open an issue at https://github.com/rcspam/dictee/issues with the log snippets listed at the bottom.

For each issue: symptom (what you see), cause (why it happens), fix (how to resolve).

Installation issues

Package conflicts between CPU and CUDA variants

Symptom: apt install ./dictee-cuda_1.3.1_amd64.deb fails with "conflicting package dictee-cpu".

Cause: The two variants are mutually exclusive — both provide dictee.

Fix:

sudo apt remove dictee-cpu
sudo apt install ./dictee-cuda_1.3.1_amd64.deb

Missing dependencies on older distros

Symptom: dpkg: dependency problems prevent configuration of dictee-cpu: pyqt6-pyside6 >= 6.5 is not installable.

Cause: Ubuntu 22.04 ships PyQt6 5.15, but dictee needs 6.5+.

Fix: Either upgrade to Ubuntu 24.04, or install PyQt6 from pip:

pip install --user 'PyQt6>=6.5'

`libcudnn9-cuda-12` not found

Symptom: Unable to locate package libcudnn9-cuda-12 during CUDA install.

Cause: NVIDIA CUDA repository not added.

Fix: Follow the distro-specific setup in GPU-Setup.

GPU issues

CUDA package on a host without a working NVIDIA driver

Since v1.3.1. If you installed dictee-cuda on a machine where the NVIDIA driver is missing, broken, or simply not exposed (typical on virtio VMs or headless containers), the daemon now logs the following and silently falls back to CPU instead of crashing in a restart loop:

[dictee] No NVIDIA GPU detected (or DICTEE_FORCE_CPU set) — using CPU provider.

The detection looks at /proc/driver/nvidia/gpus/ and /dev/nvidia0. If you want to force CPU even when a GPU is present (e.g. to share VRAM with another process), export DICTEE_FORCE_CPU=1 before starting the service:

systemctl --user edit dictee
# add:
# [Service]
# Environment=DICTEE_FORCE_CPU=1
systemctl --user restart dictee

In v1.3.0 and earlier the dictee-cuda daemon would crash with cudaSetDevice failed: driver insufficient and dictee-ptt would never connect to its socket. Upgrade to v1.3.1 to fix this without touching the driver.

GPU not detected — silent CPU fallback

Symptom: Transcription works but is slow (~1 s warm latency instead of ~0.16 s on GPU).

Check:

nvidia-smi                                         # driver present?
journalctl --user -u dictee | grep -iE "cuda|gpu"  # daemon saw GPU?

Expected output if GPU works:

dictee[12345]: Loading Parakeet-TDT on CUDA execution provider
dictee[12345]: GPU: NVIDIA GeForce RTX 4070 Laptop GPU (8 GB)

If daemon fell back to CPU:

dictee[12345]: CUDA init failed: libcudnn.so.9: cannot open shared object file

→ Install libcudnn9-cuda-12 (Debian/Ubuntu) or libcudnn9 (Fedora).

CUDA OOM on long audio

Symptom:

Failed to allocate memory for requested buffer of size 1073741824
 on /pre_encode/conv/conv.0/Conv

Cause: A known bug in the Parakeet-TDT v3 model causes the raw command-line transcribe tool to fail on audio longer than ~5:20 min on any GPU. The exact error in the logs is right operand cannot broadcast on dim 3. On low-end GPUs with ≤ 4 GB of video memory, you may hit a memory error (Failed to allocate memory on /pre_encode/conv/conv.0/Conv) on a slightly shorter file. Either way, the workaround is the same — use the chunked pipeline. See Parakeet-TDT-Deep-Dive#vram-usage--duration-limits for the engineering detail.

Fix:

Easiest (since v1.3.4): open the file in dictee-transcribe (the graphical app). It automatically splits long files into smaller chunks (180 s each, well under the bug) and reassembles them. No manual splitting, no duration cap.
Command-line alternative: use transcribe-diarize-batch <file> instead of the raw transcribe (see CLI-Reference#transcribe-diarize-batch).
If neither is available: split the file manually into pieces of 5 minutes or less (e.g. ffmpeg -i input.wav -f segment -segment_time 300 chunks-%03d.wav) and transcribe each one separately.
Note: the CPU backend doesn't help — the bug is in the model itself, not in the GPU driver.

See Parakeet-TDT-Deep-Dive#vram-usage--duration-limits for the full matrix.

cuBLAS / cuDNN version mismatch

Symptom:

libcublasLt.so.12: version `libcublasLt.so.12` not found

Cause: System cuBLAS is older than what dictee was built against.

Fix: The CUDA package bundles cuBLAS internally (via pip venv at /usr/lib/dictee/venv-cuda/) since v1.3. Make sure you didn't delete that directory and that transcribe-daemon sets LD_LIBRARY_PATH correctly. Reinstall the package if in doubt:

sudo apt reinstall dictee-cuda

Driver too old

Symptom: CUDA error: forward compatibility was attempted on non supported HW.

Fix: NVIDIA driver < 535 is unsupported. Upgrade:

# Ubuntu
sudo ubuntu-drivers install nvidia-driver-550

# Fedora
sudo dnf install --refresh akmod-nvidia
sudo reboot

Audio issues

No sound captured (PipeWire)

Symptom: Dictation starts, plasmoid shows "recording", but transcription is empty or contains garbage.

Check:

wpctl status | grep -iE "audio|source"

Fix: Make sure a source is configured as default:

wpctl set-default <SOURCE_ID>   # ID from wpctl status

Microphone stays muted after dictation

Symptom: After one successful dictation, the microphone stays muted in pavucontrol. Subsequent dictations fail silently.

Cause: dictee auto-mutes the mic during transcription to avoid bleed, and sometimes fails to re-unmute on error paths.

Fix: Manual unmute:

wpctl set-mute @DEFAULT_AUDIO_SOURCE@ 0

Or reset dictee state:

dictee --reset

PipeWire not found, falling back to ALSA

Symptom: Warning in logs: parecord not found, falling back to arecord.

Cause: PipeWire not installed (minimal XFCE/i3 setups).

Fix: Either install pipewire-pulse, or let ALSA handle it — both work, PipeWire is just preferred for mixer integration.

Daemon issues

F8 dead on a fresh Fedora / RHEL / openSUSE install

Symptom: Push-to-talk does nothing. journalctl --user -u dictee-ptt shows:

evdev.uinput.UInputError: "/dev/uinput" does not exist or is not a
character device file - verify that the uinput module is loaded

Cause: Fedora, RHEL and openSUSE do not auto-load the uinput kernel module by default (Arch and Ubuntu do). Without it, /dev/uinput is missing and dictee-ptt / dotool cannot inject keystrokes.

Fix in v1.3.1: the package now ships /etc/modules-load.d/dictee-uinput.conf and runs modprobe uinput from its post-install hook. Reinstall or upgrade to v1.3.1 to get the fix automatically.

Manual workaround on older versions:

sudo modprobe uinput                                       # load now
echo uinput | sudo tee /etc/modules-load.d/uinput.conf     # auto-load at boot
sudo udevadm control --reload-rules
sudo udevadm trigger /dev/uinput
systemctl --user restart dictee-ptt

`transcribe-daemon` socket permission denied

Symptom:

Connection refused: /run/user/1000/transcribe.sock

Cause: Daemon not running, or $XDG_RUNTIME_DIR isn't accessible.

Fix:

systemctl --user status dictee
systemctl --user restart dictee

Daemon unresponsive after suspend/resume

Symptom: Dictation hangs after laptop wakes from sleep.

Cause: CUDA context sometimes dies across suspend cycles.

Fix:

systemctl --user restart dictee

Or configure systemd to auto-restart on resume:

# ~/.config/systemd/user/dictee.service.d/override.conf
[Service]
Restart=always
RestartSec=5

Multi-user conflict

Symptom: Two users on the same machine → one user's state leaks into the other's dictations.

Cause: Fixed in v1.3-beta1. Pre-beta1 versions shared /dev/shm/.dictee_state without UID suffix.

Fix: Upgrade to v1.3.0 or later.

Post-processing issues

LLM correction returns empty text

Symptom: When LLM is enabled, final output is blank or repeats the raw ASR text.

Check:

# Is Ollama reachable?
curl http://localhost:11434/api/tags

# Is the model pulled?
ollama list

Fix:

Ollama not running: systemctl start ollama
Model missing: ollama pull gemma3:4b
Wrong endpoint: export DICTEE_OLLAMA_HOST=http://localhost:11434
Try bypassing LLM for the problematic dictation: DICTEE_PP_LLM=0 dictee

Rules not applied after edit

Symptom: You edited ~/.config/dictee/rules.conf but dictations don't reflect the new rules.

Cause: dictee-postprocess caches the rule file per invocation. Cache is fresh on every dictation, so no restart needed — but you may be testing stale output.

Fix: Run dictee-test-rules to verify the rule works. Then re-dictate.

Voice commands producing wrong output

Symptom: Saying "virgule" produces the word "virgule" in the output, not ,.

Cause: Voice command rules are disabled or overridden by a user rule.

Fix:

# List all active rules
dictee-test-rules --list

# Check if your user rule has priority
grep -n "virgule" ~/.config/dictee/rules.conf

See Rules-and-Dictionary#voice-commands for the default FR rule set.

Numbers not converted

Symptom: "vingt-trois" stays as text instead of becoming "23".

Check: number conversion is enabled in the wizard (Post-processing → Numbers).

Fix: Enable it, or check that text2num is installed:

pip show text2num
# or via system package
dpkg -l python3-text2num

UI issues

Plasmoid icon not visible

Symptom: Added widget via right-click → search → "Dictée", but nothing shows up in the panel.

Check:

kpackagetool6 -t Plasma/Applet -l | grep dictee

Fix:

Not installed: sudo apt install dictee-plasmoid or kpackagetool6 -t Plasma/Applet -i /usr/share/dictee/dictee.plasmoid
Installed but hidden: right-click panel → Enter Edit Mode → Add Widgets → Dictée → drag onto panel

Tray icon missing on GNOME

Symptom: dictee-tray is running but no icon appears in the top bar.

Cause: GNOME removed native system tray in 3.26.

Fix: Install the AppIndicator extension and reload GNOME Shell (Alt+F2, r on Xorg; logout/login on Wayland).

Plasmoid popup stays open after click

Symptom: Click on plasmoid → popup opens → click a button → popup should close but stays.

Cause: Known bug before v1.3.0 (commit 130ab95).

Fix: Upgrade to v1.3.0 or later.

Collecting logs

When reporting an issue, attach these logs:

# Main daemon
journalctl --user -u dictee -n 100 > dictee.log

# Tray
journalctl --user -u dictee-tray -n 50 > dictee-tray.log

# Setup wizard (runs in foreground, no systemd)
dictee-setup 2>&1 | tee dictee-setup.log

# Daemon detailed
DICTEE_DEBUG=1 dictee 2>&1 | tee dictee-debug.log

# GPU state
nvidia-smi > nvidia-smi.log

# Package info
dpkg -l | grep -E "dictee|cudnn|cuda" > packages.log

Then file at github.com/rcspam/dictee/issues.

Log locations summary

Component	Path
Main daemon (all ASR backends)	`journalctl --user -u dictee`
Canary daemon	`journalctl --user -u dictee-canary`
Whisper daemon	`journalctl --user -u dictee-whisper`
Vosk daemon	`journalctl --user -u dictee-vosk`
Tray	`journalctl --user -u dictee-tray`
Push-to-talk	`journalctl --user -u dictee-ptt`
State	`/dev/shm/.dictee_state_<UID>`
Socket	`$XDG_RUNTIME_DIR/transcribe.sock`

Wayland clipboard breaks Electron typing

Symptom: with "Copy transcription to clipboard" enabled in dictee-setup (or DICTEE_CLIPBOARD=true in ~/.config/dictee.conf), F9 dictation runs and the daemon logs a successful transcription, but the transcript does not appear in some target apps — typically Claude Desktop, certain terminals, and other Electron apps. The text-input caret stops blinking; clicking back into the field re-enables typing.

Cause: wl-clipboard < 2.3.0 (the default on Ubuntu LTS and other older distros) doesn't speak the ext-data-control-v1 Wayland protocol that KDE/Plasma 6.x exposes. To set the clipboard, wl-copy falls back to a workaround that briefly grabs keyboard focus via a transparent surface, then releases it. Electron apps blur their internal text input on any focus-out and don't auto-refocus on the rapid return → the keystrokes dotool injects right after the clipboard set go to a blurred input and are lost. Affects Electron in both --ozone-platform=x11 and =wayland; Qt/Wayland-native apps (Kate, etc.) handle it fine.

Fix: dictee disables the clipboard copy by default since v1.3.5. If you had enabled it, open dictee-setup and uncheck "Copy transcription to clipboard" (or set DICTEE_CLIPBOARD=false in ~/.config/dictee.conf).

To enable the clipboard option safely, upgrade wl-clipboard to ≥ 2.3.0:

Arch — already current via pacman.

Ubuntu 24.04 / Debian stable — backport, or build from source:

git clone -b v2.3.0 https://github.com/bugaevc/wl-clipboard
cd wl-clipboard && meson setup build && ninja -C build && sudo ninja -C build install

Fedora Rawhide — usually current.

Once wl-clipboard ≥ 2.3.0 is installed, wl-copy uses the focus-neutral ext-data-control-v1 path on KDE and the clipboard set no longer steals focus.

GNOME caveat: Mutter doesn't yet expose ext-data-control-v1 in stable releases (mutter#524 still open). Even with wl-clipboard ≥ 2.3.0, the focus-stealing fallback still triggers there → keep the clipboard option off on GNOME until Mutter ships ext-data-control support.

Next steps

FAQ — design questions, comparisons
GPU-Setup — GPU-specific setup details
CLI-Reference#exit-codes — what each exit code means
Developer-Guide — internals for deeper debugging

📖 dictee Wiki

🇬🇧 Home · 🇫🇷 Accueil

Getting started / Premiers pas

Installation · 🇬🇧 · 🇫🇷
Setup-Wizard · 🇬🇧 · 🇫🇷
Configuration · 🇬🇧 · 🇫🇷
Plasmoid-Widget · 🇬🇧 · 🇫🇷
Tray-Icon · 🇬🇧 · 🇫🇷
Keyboard-Shortcuts · 🇬🇧 · 🇫🇷
Voice-Commands · 🇬🇧 · 🇫🇷
GPU-Setup · 🇬🇧 · 🇫🇷
Diarization · 🇬🇧 · 🇫🇷
LLM-Diarization · 🇬🇧 · 🇫🇷

Speech recognition / ASR

ASR-Backends · 🇬🇧 · 🇫🇷
Parakeet-TDT-Deep-Dive · 🇬🇧 · 🇫🇷
Canary-1B-Deep-Dive · 🇬🇧 · 🇫🇷

Translation / Traduction

Translation · 🇬🇧 · 🇫🇷
Ollama-Setup · 🇬🇧 · 🇫🇷

Post-processing / Post-traitement

Overview · 🇬🇧 · 🇫🇷
Rules-and-Dictionary · 🇬🇧 · 🇫🇷
LLM-Correction · 🇬🇧 · 🇫🇷
Numbers-Dates-Continuation · 🇬🇧 · 🇫🇷

CLI

CLI-Reference · 🇬🇧 · 🇫🇷

Reference / Référence

Troubleshooting · 🇬🇧 · 🇫🇷
FAQ · 🇬🇧 · 🇫🇷
Developer-Guide · 🇬🇧 · 🇫🇷
Changelog · 🇬🇧 · 🇫🇷

🏠 Repo · 📦 Releases · 🐛 Issues

Troubleshooting

Troubleshooting

Table of Contents

Installation issues

Package conflicts between CPU and CUDA variants

Missing dependencies on older distros

libcudnn9-cuda-12 not found

GPU issues

CUDA package on a host without a working NVIDIA driver

GPU not detected — silent CPU fallback

CUDA OOM on long audio

cuBLAS / cuDNN version mismatch

Driver too old

Audio issues

No sound captured (PipeWire)

Microphone stays muted after dictation

PipeWire not found, falling back to ALSA

Daemon issues

F8 dead on a fresh Fedora / RHEL / openSUSE install

transcribe-daemon socket permission denied

Daemon unresponsive after suspend/resume

Multi-user conflict

Post-processing issues

LLM correction returns empty text

Rules not applied after edit

Voice commands producing wrong output

Numbers not converted

UI issues

Plasmoid icon not visible

Tray icon missing on GNOME

Plasmoid popup stays open after click

Collecting logs

Log locations summary

Wayland clipboard breaks Electron typing

Next steps

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

`libcudnn9-cuda-12` not found

`transcribe-daemon` socket permission denied