Troubleshooting SL5 Aura¶

Quick Diagnosis¶

Always start here:

# Check the main log:
tail -50 log/aura_engine.log

# Is Aura running?
pgrep -a -f aura_engine.py

# Is the file watcher running?
pgrep -a type_watcher

Problem: Aura Does Not Start¶

Symptom: No startup sound, no process visible in pgrep.

Check the log:

tail -30 log/aura_engine.log

Common causes:

Error in log	Fix
`ModuleNotFoundError`	Run setup script again: `bash setup/manjaro_arch_setup.sh`
`No module named 'objgraph'`	`.venv` was recreated — reinstall: `pip install -r requirements.txt`
`Address already in use`	Kill old process: `pkill -9 -f aura_engine`
`Model not found`	Re-run setup to download missing models
`pygame.mixer not available`	See “No Sound on Startup” below

Problem: No Sound on Startup (pygame.mixer)¶

Symptom: Warning or error about pygame.mixer not available. Aura starts but plays no sounds.

Cause: Your system’s pygame build does not include audio support, or SDL2 audio libraries are missing.

Fix on Arch/Manjaro:

sudo pacman -S sdl2_mixer
pip install pygame-ce --upgrade

Fix on Ubuntu/Debian:

sudo apt install libsdl2-mixer-2.0-0
pip install pygame-ce --upgrade

Aura will continue to work without sound — this is not a fatal error.

Problem: Aura Crashes After First Dictation¶

Symptom: Works once, then dies silently.

Check stderr:

cat /tmp/aura_stderr.log | tail -30

If you see Segmentation Fault or double free:

This is a known issue on systems with glibc 2.43+ (CachyOS, newer Arch).

sudo pacman -S mimalloc

mimalloc is automatically used by the start script if installed. Confirm it is active — you should see this on startup:

Info: Using mimalloc for improved memory management (/usr/lib/libmimalloc.so).

Problem: Trigger Key Does Nothing¶

Symptom: You press the hotkey but nothing happens — no sound, no text.

Check if the file watcher is running:

pgrep -a type_watcher

If nothing appears, restart Aura:

./scripts/restart_venv_and_run-server.sh

Check if the trigger file is being created:

ls -la /tmp/sl5_record.trigger

If the file is never created, your hotkey is not working — see below.

Problem: Hotkey Not Working on Wayland¶

Symptom: CopyQ is installed and configured, but pressing the hotkey does nothing on a Wayland session.

Cause: CopyQ global hotkeys do not work reliably on Wayland without additional configuration. This affects KDE Plasma, GNOME, and other Wayland compositors.

Option 1: KDE System Settings (Recommended for KDE Plasma)¶

Open System Settings → Shortcuts → Custom Shortcuts
Create a new shortcut of type Command/URL
Set the command to:
```
touch /tmp/sl5_record.trigger
```
Assign your preferred key combination (e.g. F9 or Ctrl+Alt+Space)

Option 2: dotool (Works on any Wayland compositor)¶

# Install dotool:
sudo pacman -S dotool        # Arch/Manjaro
# or
sudo apt install dotool      # Ubuntu (if available)

Then use your desktop’s shortcut manager to run:

touch /tmp/sl5_record.trigger

Option 3: ydotool¶

sudo pacman -S ydotool
sudo systemctl enable --now ydotool

Then configure your shortcut to run:

touch /tmp/sl5_record.trigger

Option 4: GNOME (using dconf / GNOME Settings)¶

Open Settings → Keyboard → Custom Shortcuts
Add a new shortcut with command:
```
touch /tmp/sl5_record.trigger
```
Assign a key combination

Option 5: CopyQ with Wayland fix¶

Some Wayland compositors allow CopyQ to work if started with:

QT_QPA_PLATFORM=xcb copyq

This forces CopyQ to use XWayland, which supports global hotkeys.

Problem: Text Appears But Without Corrections¶

Symptom: Dictation works but everything stays lowercase, no grammar fixes.

Check if LanguageTool is running:

curl -s http://127.0.0.1:8082/v2/languages | head -5

If this returns an error, LanguageTool is not running. Aura should start it automatically — check the log for errors related to LanguageTool:

grep -i "languagetool\|LT\|8082" log/aura_engine.log | tail -10

Check LanguageTool log:

cat log/languagetool_server.log | tail -20

Problem: Aura Hangs in DEV_MODE¶

Symptom: With DEV_MODE = 1, Aura hangs after the first trigger and stops responding.

Cause: High log volume from multiple threads overloads the logging system.

Fix: Add a log filter in config/filters/settings_local_log_filter.py:

LOG_ONLY = [
    r"Successfully",
    r"CRITICAL",
    r"📢📢📢 #",
    r"window_title",
    r":st:",
]
LOG_EXCLUDE = []

Save the file — Aura reloads the filter automatically. No restart needed.

Problem: plugins.zip Grows Endlessly / High CPU¶

Symptom: 100% CPU, fans at full speed, plugins.zip grows without stopping.

Cause: The secure packer is repackaging files in an infinite loop.

Fix: Make sure .blob and .zip files are excluded from the timestamp scan. Check scripts/py/func/secure_packer_lib.py around line 86:

if file.startswith('.') or file.endswith('.pyc') or file.endswith('.blob') or file.endswith('.zip'):
    continue

If this line is missing, add it.

Problem: Rules Not Firing¶

Symptom: You dictate a trigger phrase but the rule does nothing.

Checklist:

Is the rule in the correct file? (FUZZY_MAP_pre.py = before LanguageTool, FUZZY_MAP.py = after)
Is the map file saved? Aura reloads on save — check the log for Successfully reloaded.
Does the pattern match what Vosk actually transcribes? Check the log for the raw transcription:
```
grep "Yielding chunk" log/aura_engine.log | tail -5
```
Is only_in_windows set and the wrong window is active?
Is a more general rule matching first? Rules are processed top-to-bottom — put specific rules before general ones.

Collecting Logs for Bug Reports¶

When reporting an issue, please include:

# Last 100 lines of main log:
tail -100 log/aura_engine.log

# Crash output:
cat /tmp/aura_stderr.log

# System info:
uname -a
python3 --version

Post to: GitHub Issues