Skip to content

FAQ

Jump to bottom
BottyIvan edited this page Jun 15, 2026 · 2 revisions

FAQ and Troubleshooting

Frequently asked questions and solutions to common issues.

Table of Contents

General Questions

What is Launcher?

Launcher is a modern desktop application launcher for Linux built with GTK4 and Adwaita. It provides instant search capabilities for installed applications, a built-in calculator, and an extensible architecture for adding custom functionality.

What platforms does Launcher support?

Launcher is designed for Linux desktop environments. It works best on:

  • GNOME (primary target)
  • KDE Plasma
  • XFCE
  • Other GTK4-compatible desktop environments

Is Launcher free and open source?

Yes! Launcher is licensed under GPL-3.0-or-later and is completely free and open source.

How is Launcher different from GNOME's built-in search?

  • Standalone: Launcher is a separate application
  • Faster startup: Optimized for quick launches
  • More customizable: Extension system and preferences
  • Calculator built-in: No need to switch apps
  • Portable: Works across different desktop environments

How much memory does Launcher use?

Launcher typically uses 30-50MB of RAM when running, with minimal CPU usage during idle. Memory usage may increase temporarily during application discovery and caching.

Installation Issues

"GTK4 not found" error

Problem: Missing GTK4 libraries

Solution:

# Ubuntu/Debian
sudo apt install libgtk-4-1 gir1.2-gtk-4.0

# Fedora
sudo dnf install gtk4

# Arch Linux
sudo pacman -S gtk4

"PyGObject import error"

Problem: Python GTK bindings not installed

Solution:

# Ubuntu/Debian
sudo apt install python3-gi python3-gi-cairo

# Fedora
sudo dnf install python3-gobject

# Arch Linux
sudo pacman -S python-gobject

# Or via pip (not recommended)
pip3 install PyGObject

Flatpak build fails

Problem: Missing flatpak-builder or dependencies

Solution:

# Install flatpak-builder
sudo apt install flatpak-builder  # Ubuntu/Debian
sudo dnf install flatpak-builder  # Fedora
sudo pacman -S flatpak-builder    # Arch

# Ensure you have GNOME runtime
flatpak install flathub org.gnome.Platform//48 org.gnome.Sdk//48

# Clean and rebuild
rm -rf build-dir .flatpak-builder
flatpak-builder --user --install --force-clean build-dir cloud.ivanbotty.Launcher.yaml

"Permission denied" when installing

Problem: Insufficient permissions

Solution:

  • Use --user flag for user-level install
  • Or use sudo for system-wide install
  • Check file permissions in the repository directory

Application doesn't start after installation

Problem: Missing dependencies or configuration

Solution:

# For Flatpak, check if installed
flatpak list | grep Launcher

# Try running with verbose output
flatpak run -v cloud.ivanbotty.Launcher

# Check logs
journalctl --user -f | grep launcher

# For source install, check Python path
python3 -c "import gi; gi.require_version('Gtk', '4.0'); from gi.repository import Gtk"

Usage Questions

How do I open Launcher?

Methods:

  1. From application menu: Search for "Launcher"
  2. Command line: flatpak run cloud.ivanbotty.Launcher
  3. Keyboard shortcut: Configure in system settings (e.g., Super+Space)

Applications are not showing up

Problem: Desktop files not found or cached

Solution:

  1. Check if applications have .desktop files
  2. Verify desktop file locations: 
    ls /usr/share/applications
ls ~/.local/share/applications
  3. Clear cache and restart: 
    rm -rf ~/.local/share/cloud.ivanbotty.Launcher/cache
  4. For Flatpak apps, ensure they're visible: 
    ls ~/.local/share/flatpak/exports/share/applications

Icons are missing or incorrect

Problem: Icon theme or cache issues

Solution:

  1. Install a complete icon theme: 
    sudo apt install adwaita-icon-theme
  2. Update icon cache: 
    gtk-update-icon-cache
  3. Check GTK settings: 
    gsettings get org.gnome.desktop.interface icon-theme

Search is not finding apps I know are installed

Problem: Search algorithm or desktop file issues

Solution:

  1. Try exact name of the application
  2. Check if app has NoDisplay=true in desktop file
  3. Verify desktop file format
  4. Enable "show hidden apps" in preferences
  5. Check application categories and keywords

How do I use the calculator?

Usage: Just type mathematical expressions directly:

Type: 2 + 2
Result: 4

Type: sqrt(16)
Result: 4.0

Type: sin(pi/2)
Result: 1.0

Supported operations:

  • Basic: +, -, *, /, ** (power), % (modulo)
  • Functions: sqrt, sin, cos, tan, log, abs, ceil, floor
  • Constants: pi, e

How do I switch between compact and extended view?

Methods:

  1. Press Tab key
  2. Click view toggle button (if available)
  3. Preference is saved automatically

Performance Issues

Launcher is slow to start

Possible causes and solutions:

  1. First launch: Cache is being built

    • Solution: Wait for initial scan to complete
    • Subsequent launches will be faster

  2. Large number of applications:

    • Solution: Increase cache size in preferences
    • Consider disabling unused Flatpak remotes

  3. Slow disk I/O:

    • Solution: Use SSD if possible
    • Check disk health

  4. Debug mode enabled:

    • Solution: Disable debug logging
    unset LAUNCHER_DEBUG
unset LAUNCHER_LOG_LEVEL

Search results appear slowly

Problem: Database queries or search algorithm

Solution:

  1. Ensure instant search is enabled in preferences
  2. Reduce max results limit
  3. Disable "search in descriptions" for faster search
  4. Clear and rebuild cache

High memory usage

Problem: Memory leak or large cache

Solution:

  1. Restart Launcher periodically
  2. Check cache size settings
  3. Disable unused extensions
  4. Report persistent memory issues on GitHub

Application hangs or freezes

Problem: Thread deadlock or UI blocking

Solution:

  1. Check system logs for errors
  2. Try disabling extensions one by one
  3. Run with debug logging: 
    LAUNCHER_LOG_LEVEL=DEBUG flatpak run cloud.ivanbotty.Launcher
  4. Report issue with logs

Configuration Problems

Preferences not saving

Problem: Database write permissions or corruption

Solution:

# Check database location
ls -la ~/.local/share/cloud.ivanbotty.Launcher/

# For Flatpak
ls -la ~/.var/app/cloud.ivanbotty.Launcher/data/

# Check permissions
chmod 644 ~/.local/share/cloud.ivanbotty.Launcher/launcher.db

# If corrupted, backup and reset
mv launcher.db launcher.db.bak
# Restart Launcher to create new database

Settings reset after each launch

Problem: Database not persisting or Flatpak permissions

Solution:

# For Flatpak, ensure data directory is writable
flatpak override --user --filesystem=xdg-data/cloud.ivanbotty.Launcher cloud.ivanbotty.Launcher

# Check if database is in read-only location

Custom keyboard shortcuts not working

Problem: System-wide shortcuts or conflict

Solution:

  1. Use system settings to set global shortcut
  2. Ensure no conflicts with existing shortcuts
  3. Check desktop environment documentation:
    • GNOME: Settings → Keyboard → Custom Shortcuts
    • KDE: System Settings → Shortcuts

Extension Issues

Extension won't enable

Problem: Missing dependencies or configuration

Solution:

  1. Check extension requirements
  2. For AI extension, set API key: 
    export GEMINI_API_KEY="your-api-key"
  3. Check extension YAML syntax
  4. View logs for error messages

AI Assistant not responding

Problem: API key, network, or API issues

Solution:

  1. Verify API key is set: 
    echo $GEMINI_API_KEY
  2. Check network connectivity
  3. Verify API quota/limits
  4. Check API endpoint is accessible

Math calculator giving wrong results

Problem: Expression parsing or operator precedence

Solution:

  1. Use parentheses for complex expressions
  2. Check function names (e.g., sqrt not square_root)
  3. Verify angle mode (radians vs degrees)
  4. Report calculation bugs on GitHub

Extension conflicts

Problem: Multiple extensions handling same input

Solution:

  1. Check extension priorities
  2. Disable conflicting extensions
  3. Reorder extensions in configuration

Development Questions

How do I set up a development environment?

See the detailed Contributing Guide.

Quick setup:

git clone https://github.com/BottyIvan/launcher-app.git
cd launcher-app
pip3 install --user PyGObject google-generativeai black flake8 mypy
python3 -m cloud.ivanbotty.Launcher

Tests are failing

Problem: Missing dependencies or test environment issues

Solution:

# Install test dependencies
pip3 install --user PyGObject

# Run tests with verbose output
python3 -m unittest discover tests/ -v

# Check specific failing test
python3 -m unittest tests.test_utils.TestAppInitUtils -v

# Some tests may be skipped if GTK4 is not available in test environment

How do I create a new extension?

See Architecture and API Reference.

Basic steps:

  1. Create handler class extending BaseInputHandler
  2. Create service class with business logic
  3. Add extension definition to extensions.yaml
  4. Test and submit PR

Type checking errors with MyPy

Problem: Type hints or stub files

Solution:

# Install type stubs
pip3 install types-PyYAML

# Run MyPy with relaxed settings for GTK
mypy --ignore-missing-imports cloud/ivanbotty

Platform-Specific Issues

GNOME

Wayland issues:

# Force X11 if Wayland has issues
GDK_BACKEND=x11 flatpak run cloud.ivanbotty.Launcher

HiDPI scaling:

# Adjust scaling
GDK_SCALE=2 flatpak run cloud.ivanbotty.Launcher

KDE Plasma

Theme inconsistencies:

  • Install Breeze-GTK theme for better integration
  • Or set GTK theme to Adwaita

Qt/GTK mixing:

  • Visual style may differ from Qt apps
  • This is expected behavior

XFCE

Compositor issues:

  • Enable compositor for smooth animations
  • Settings → Window Manager Tweaks → Compositor

Tiling Window Managers (i3, Sway)

Floating window:

# For i3 config
for_window [app_id="cloud.ivanbotty.Launcher"] floating enable

# For Sway
for_window [app_id="cloud.ivanbotty.Launcher"] floating enable, sticky enable

Getting More Help

Check Logs

System logs:

# For systemd
journalctl --user -f | grep launcher

# Application logs (if enabled)
tail -f ~/.local/share/cloud.ivanbotty.Launcher/launcher.log

Debug mode:

LAUNCHER_LOG_LEVEL=DEBUG flatpak run cloud.ivanbotty.Launcher 2>&1 | tee launcher-debug.log

Report an Issue

If your problem isn't covered here:

  1. Search existing issues: https://github.com/BottyIvan/launcher-app/issues
  2. Gather information:
    • Operating system and version
    • Desktop environment
    • Launcher version
    • Steps to reproduce
    • Error messages or logs
  3. Create new issue: Provide all gathered information
  4. Be patient: Maintainers will respond when available

Community Support

Quick Troubleshooting Checklist

When something goes wrong, try these steps:

  1. ☐ Restart Launcher
  2. ☐ Check system updates
  3. ☐ Clear cache and restart
  4. ☐ Check logs for errors
  5. ☐ Try with default configuration
  6. ☐ Verify dependencies are installed
  7. ☐ Check GitHub issues for similar problems
  8. ☐ Enable debug logging
  9. ☐ Report issue with detailed information

Additional Resources

Clone this wiki locally