Troubleshooting

This guide covers common issues and their solutions.

Quick Diagnosis

Symptom	Cause	Solution
Launcher doesn't appear	Daemon not running	Run hamr (auto-starts daemon) or check systemctl --user status hamr-daemon
"Connection refused" error	Socket not created	Ensure daemon is running: pgrep hamr-daemon or restart with hamr
Window appears but immediately closes	Compositor lacks layer-shell support	Verify compositor supports layer-shell (see Compositor Support)
No search results	Index not built	Run hamr index to rebuild the application index
Plugin not responding	Plugin crashed or timeout	Check logs: grep "plugin" /tmp/hamr-daemon.log \| tail -20
Slow startup	Large plugin index	Review ~/.local/share/hamr/index/ size; consider disabling unused plugins
Keybinding doesn't work	Compositor config issue	Verify binding syntax in compositor config; test with hamr toggle manually
GTK theme not applied	GTK4 theme missing	Install a GTK4-compatible theme; Hamr uses GTK4, not GTK3

Daemon Issues

Daemon won't start

1. Check if another instance is running:

   pgrep -a hamr-daemon
   

2. Check for socket conflicts:

   ls -la /tmp/hamr-*.sock
   # Remove stale socket if daemon isn't running
   rm /tmp/hamr-*.sock
   

3. Check logs for errors:

   tail -50 /tmp/hamr-daemon.log
   

Daemon crashes on startup

Common causes:

• Missing GTK4: Install GTK4 4.20+ and gtk4-layer-shell
• Missing plugins directory: If ~/.config/hamr/plugins is missing, run hamr install to set up user directories
• Corrupt config: Move ~/.config/hamr/config.json and restart

Plugin Issues

Plugin not found

1. Verify plugin exists:

   ls ~/.local/share/hamr/plugins/
   

2. Check plugin manifest is valid JSON:

   cat ~/.local/share/hamr/plugins/<plugin>/manifest.json | python -m json.tool
   

3. Ensure plugin has execute permission:

   chmod +x ~/.local/share/hamr/plugins/<plugin>/main.py
   

Plugin returns no results

1. Test plugin directly:

   hamr test <plugin> "your query"
   

2. Check plugin logs:

   grep "<plugin>" /tmp/hamr-daemon.log | tail -30
   

3. Enable plugin debug mode:

   HAMR_PLUGIN_DEBUG=1 hamr daemon
   

Plugin timeout

Plugins have a default timeout. If a plugin is slow:

1. Check if external service is reachable (for network plugins)
2. Review plugin code for blocking operations
3. Consider increasing timeout in plugin manifest

Display Issues

Window appears in wrong position

Layer-shell positioning depends on compositor support:

1. Ensure gtk4-layer-shell is installed
2. Check compositor-specific settings for layer positioning
3. Try different anchor settings in config

Window doesn't receive keyboard focus

1. Verify layer-shell is working:

   # Should show layer-shell in use
   grep -i "layer" /tmp/hamr-daemon.log
   

2. Some compositors require explicit focus rules for layer surfaces

Blurry or scaled incorrectly

GTK4 respects GDK_SCALE environment variable:

# Force 1x scaling
GDK_SCALE=1 hamr-gtk

# Force 2x scaling
GDK_SCALE=2 hamr-gtk

Performance Issues

Slow search results

1. Check index size:

   du -sh ~/.local/share/hamr/index/
   

2. Rebuild index:

   hamr index --rebuild
   

3. Disable plugins you don't use in config

High memory usage

1. Check plugin count:

   ls ~/.local/share/hamr/plugins/ | wc -l
   

2. Disable daemon plugins that aren't needed

3. Check for plugin memory leaks in logs

Log Files

Debug builds write logs to /tmp/:

Component	Log Path	Symlink
Daemon	/tmp/hamr-daemon-YYYYMMDD_HHMMSS.log	/tmp/hamr-daemon.log
TUI	/tmp/hamr-tui-YYYYMMDD_HHMMSS.log	/tmp/hamr-tui.log

Enable verbose logging

# Most verbose
RUST_LOG=trace hamr daemon

# Debug for hamr crates only
RUST_LOG=hamr=debug hamr daemon

# Warnings and errors only
RUST_LOG=warn hamr daemon

Search logs for errors

# Find all errors
grep -i "error\|warn" /tmp/hamr-daemon.log

# Plugin-specific issues
grep "plugin" /tmp/hamr-daemon.log | tail -20

# Action handling
grep "handle_action\|Forwarding" /tmp/hamr-daemon.log

Getting Help

If these steps don't resolve your issue:

1. Check existing GitHub Issues
2. Collect logs: tail -200 /tmp/hamr-daemon.log > hamr-debug.log
3. Open a new issue with:
4. Hamr version (hamr --version)
5. Compositor and version
6. Distribution
7. Relevant log output