Skip to content

Troubleshooting

Jump to bottom
Firstp1ck edited this page Apr 9, 2026 · 9 revisions

Troubleshooting

This guide helps you diagnose and resolve common issues with Pacsea. If you encounter a problem, follow these steps to gather information and find a solution.

Related guides:

Before Reporting Issues

IMPORTANT: Always run Pacsea with debug logging enabled when reporting issues. This provides crucial diagnostic information.

Enabling Debug Logging

Method 1: Using the verbose flag (recommended)

pacsea --verbose
# or short form:
pacsea -v

Method 2: Using log-level flag

pacsea --log-level debug

Method 3: Using environment variable

RUST_LOG=pacsea=debug pacsea

For very detailed tracing (preflight operations):

PACSEA_PREFLIGHT_TRACE=1 pacsea --log-level trace

Locating Log Files

Pacsea writes logs to:

~/.config/pacsea/logs/pacsea.log

To view the latest log entries:

tail -f ~/.config/pacsea/logs/pacsea.log
# or view the entire log:
cat ~/.config/pacsea/logs/pacsea.log

Extracting Warnings and Errors from Logs

When troubleshooting, it's often helpful to filter the log file for warnings and errors only. Here are several methods:

Method 1: Using grep (recommended)

# Extract all warnings and errors
grep -E "(WARN|ERROR|error|warn)" ~/.config/pacsea/logs/pacsea.log

# Case-insensitive search
grep -iE "(warn|error)" ~/.config/pacsea/logs/pacsea.log

# Show context (5 lines before and after each match)
grep -E "(WARN|ERROR|error|warn)" -A 5 -B 5 ~/.config/pacsea/logs/pacsea.log

# Extract only from the last 1000 lines (most recent)
tail -1000 ~/.config/pacsea/logs/pacsea.log | grep -E "(WARN|ERROR|error|warn)"

Method 2: Extract warnings and errors separately

# Extract only warnings
grep -i "warn" ~/.config/pacsea/logs/pacsea.log > warnings.txt

# Extract only errors
grep -i "error" ~/.config/pacsea/logs/pacsea.log > errors.txt

# View both files
cat warnings.txt errors.txt

Method 3: Using awk (for more control)

# Extract lines containing WARN or ERROR (case-insensitive)
awk '/[Ww][Aa][Rr][Nn]|[Ee][Rr][Rr][Oo][Rr]/' ~/.config/pacsea/logs/pacsea.log

# Extract with timestamps
awk '/[Ww][Aa][Rr][Nn]|[Ee][Rr][Rr][Oo][Rr]/ {print}' ~/.config/pacsea/logs/pacsea.log

Method 4: Save filtered output to a file

# Save all warnings and errors to a separate file for easy sharing
grep -E "(WARN|ERROR|error|warn)" ~/.config/pacsea/logs/pacsea.log > pacsea-errors-warnings.txt

# Then you can easily share this file when reporting issues
cat pacsea-errors-warnings.txt

Method 5: Real-time monitoring of errors/warnings

# Watch for new warnings/errors as they occur
tail -f ~/.config/pacsea/logs/pacsea.log | grep --line-buffered -E "(WARN|ERROR|error|warn)"

Example output:

2024-01-15 10:23:45.123 [WARN] failed to open log file; using stderr
2024-01-15 10:23:46.456 [ERROR] Failed to execute pacman -Fl package-name: No such file or directory
2024-01-15 10:23:47.789 [WARN] AUR search failed: timeout

Pro tip: When reporting issues, include the filtered warnings/errors output along with a brief description of what you were doing when the issue occurred.

When reporting issues, please include:

  1. Warnings and errors from logs (see Extracting Warnings and Errors from Logs section above)
  2. Your Pacsea version (pacsea --version or check AUR package)
  3. Your distribution and version
  4. Terminal emulator and display server (Wayland/X11)
  5. Steps to reproduce the issue
  6. Relevant log sections if needed (use the extraction methods above to filter)

Common Issues and Solutions

Fingerprint / PAM prompts don’t appear (or sudo seems to hang)

Symptoms:

  • You expect a fingerprint prompt, but Pacsea never progresses.
  • You see password prompts that don’t accept input, or authentication appears stuck.

What to know:

  • Pacsea can either pipe a password to the privilege tool (auth_mode = prompt) or hand off auth to the terminal (auth_mode = interactive).
  • Fingerprint auth is handled by PAM (e.g. pam_fprintd) and typically works best with interactive mode.

Fix:

  1. Edit ~/.config/pacsea/settings.conf and set: 
    auth_mode = interactive
  2. If you prefer doas, also set: 
    privilege_tool = doas
    and ensure OpenDoas is configured appropriately (often with persist in /etc/doas.conf) so you don’t get reprompted for every sub-command.

Long-running operations warn about re-authentication

Symptoms:

  • You see a warning before install/update/remove/downgrade about possible re-authentication pauses.
  • Long AUR builds or update flows pause and ask for auth again.

What to know:

  • Pacsea now performs a readiness check for long-running privileged operations.
  • If your tool/policy likely expires credentials mid-run, a one-time warning appears so you can decide whether to continue.

Fix options:

  1. For sudo: configure credential cache timeout in a dedicated sudoers drop-in: 
    sudo visudo -f /etc/sudoers.d/99-pacsea-timestamp
# example line:
# Defaults timestamp_timeout=30
sudo chmod 0440 /etc/sudoers.d/99-pacsea-timestamp
  2. For doas: configure a persist policy in /etc/doas.conf (and PAM/fingerprint stack if used on your system).
  3. Open the built-in helpers:
    • Options → Optional Deps → sudo_timestamp_setup
    • Options → Optional Deps → doas_persist_setup

Doas persist setup helper says configuration is not effective

Symptoms:

  • The doas_persist_setup helper still shows warnings after you edited doas.conf.

Checks:

  1. Confirm syntax and ordering in /etc/doas.conf: 
    doas -C /etc/doas.conf
  2. Confirm your intended rule includes persist and matches your user/group and command scope.
  3. Re-test from terminal: 
    doas -n true   # non-interactive check
doas true      # interactive auth check
  4. Restart terminal sessions if your PAM/fingerprint stack was changed.

If still failing:

  • Run Pacsea with debug logs (pacsea --verbose) and inspect ~/.config/pacsea/logs/pacsea.log for readiness-check hints.

BlackArch packages or filter chip missing

Symptoms:

  • BlackArch packages never appear in search, or the [BlackArch] chip is absent from the Results title bar while you expect BlackArch on your system.

What to know:

  • Pacsea only consumes an already-configured BlackArch mirror. It does not add [blackarch] to /etc/pacman.conf or install keys.

Checks:

  1. Repo enabled in pacman

    grep -E '^\[blackarch\]' /etc/pacman.conf

    If there is no [blackarch] section, follow BlackArch’s install instructions first.

  2. Database sync and list output

    sudo pacman -Sy
pacman -Sl blackarch | head

    If this prints nothing (or errors), Pacsea’s official index merge has no BlackArch data—fix mirror/sync issues with pacman first.

  3. Case and name

    • Pacsea recognizes the repository name blackarch (matching is case-insensitive). Custom section names that are not the expected repo id may not be classified as BlackArch.

  4. Debug logging

    RUST_LOG=pacsea=debug pacsea --dry-run

    Then search for a known BlackArch package and inspect ~/.config/pacsea/logs/pacsea.log if results still look wrong.

Expected behavior once configured:

  • BlackArch packages appear alongside other official repos, labeled BlackArch, with a clickable [BlackArch] filter chip (default: visible/on, like other optional official filters).

Custom repos, Chaotic-AUR, and “wrong” AUR installs

Symptoms:

  • You queued an AUR package, but paru / yay built or installed from a sync repo instead (e.g. Chaotic-AUR ships the same pkgname).
  • After enabling a new repo, pacman -Syu or helpers want to replace an AUR build with a repo build and you are unsure it is safe.
  • Overlap or “reopen Repositories” behavior seems stuck after a failed sudo step.

What to know:

  • Pacsea forces AUR-only queue segments to use paru / yay -S --aur (when those helpers are used) so the helper does not satisfy the request from sync databases. Official/sync names still go through pacman as before.
  • If the same name appears as both an AUR row and a sync row in the current results, Pacsea shows a one-shot warning before continuing the AUR install path.
  • After Repositories → Apply, a foreign overlap wizard may appear when pacman -Qm names intersect the new repo’s pacman -Sl list—optional migration is always explicit (see How to use Pacsea — Custom repositories).
  • A failed privileged finish clears pending overlap and “resume Repositories” state so you do not get ghost wizards.

Checks:

  1. Confirm helper and pacman are on PATH (which paru yay pacman).
  2. Reproduce with pacsea --dry-run to inspect printed commands.
  3. Inspect ~/.config/pacsea/repos.conf and /etc/pacman.d/pacsea-repos.conf after apply (and pacman.conf Include markers) if sync behavior surprises you.

AUR Search Errors

Symptoms:

  • No AUR packages appear in search results
  • Error messages about AUR connectivity
  • Timeout errors when searching

Solutions:

  1. Check your network connection:

    ping aur.archlinux.org
curl -I https://aur.archlinux.org

  2. Verify AUR helper is installed:

    which paru  # or: which yay

    If neither is found, install one:

    # Install paru
git clone https://aur.archlinux.org/paru.git
cd paru && makepkg -si

# Or install yay
git clone https://aur.archlinux.org/yay.git
cd yay && makepkg -si

  3. Test AUR helper directly:

    paru -Ss package-name  # or: yay -Ss package-name

  4. Check firewall/proxy settings:

    • Ensure port 443 (HTTPS) is not blocked
    • If behind a proxy, configure it in your environment

  5. Clear Pacsea cache:

    pacsea --clear-cache

  6. Run with debug logging to see detailed error messages:

    pacsea --verbose
# Check ~/.config/pacsea/logs/pacsea.log for specific errors

Installs Don't Start

Symptoms:

  • Nothing happens when pressing Enter to install
  • No terminal window opens
  • Installation commands don't execute

Solutions:

  1. Verify terminal emulator is installed: Pacsea tries these terminals in order:

    • alacritty, kitty, ghostty, xterm
    • gnome-terminal, konsole, xfce4-terminal, tilix, mate-terminal
    • If no terminal emulator is found, Pacsea attempts to execute commands directly via bash, but this may not work properly if you're not already in a terminal environment

    Install at least one terminal emulator:

    sudo pacman -S alacritty  # or your preferred terminal

  2. Set preferred terminal in config: Edit ~/.config/pacsea/settings.conf:

    preferred_terminal = alacritty

    Changes to preferred_terminal take effect automatically (settings are read fresh from disk). For theme changes, press Ctrl+R to reload.

  3. Test sudo access:

    sudo -v

    If you use doas, test it instead:

    doas -n true   # passwordless check (will fail if a prompt would be required)
doas true      # interactive auth

    If this fails, configure sudo properly:

    # Add your user to wheel group (if not already)
sudo usermod -aG wheel $USER
# Log out and back in for changes to take effect

  4. Verify sudoers configuration: Ensure your user can run sudo without password (optional but recommended). Pacsea supports passwordless sudo for install, update, and downgrade: when configured, no password prompt is shown for those operations. Remove operations always ask for a password for safety. You must also enable passwordless sudo in Pacsea settings: set use_passwordless_sudo = true in settings.conf (Config → Settings), or it will not be used. See Configuration and How to use Pacsea for details. If you want fingerprint/PAM prompts, prefer auth_mode = interactive (see above).

    sudo visudo
# Add line: yourusername ALL=(ALL) NOPASSWD: ALL

  5. Check terminal permissions: Ensure the terminal binary is executable:

    ls -l $(which alacritty)  # or your terminal

  6. Run with debug logging:

    pacsea --verbose
# Look for terminal-related errors in ~/.config/pacsea/logs/pacsea.log

Package Installation Fails

Symptoms:

  • Installation starts but fails mid-process
  • Dependency errors
  • Permission denied errors

Solutions:

  1. Verify disk space:

    df -h

  2. Check for conflicting packages:

    sudo pacman -Syu  # Update system first

  3. Review package dependencies:

    • Use the Preflight modal (if skip_preflight = false in settings.conf)
    • Check for dependency conflicts before installing

  4. For AUR packages:

    • Ensure base-devel group is installed: 
      sudo pacman -S --needed base-devel
    • Check PKGBUILD for special requirements
    • Review AUR comments for known issues

  5. Run installation manually to see detailed errors:

    # For official packages:
sudo pacman -S package-name

# For AUR packages:
paru -S package-name  # or: yay -S package-name

Configuration Issues

Symptoms:

  • Config changes don't take effect
  • Errors about unknown config keys
  • Theme/colors not applying
  • Import operations fail with invalid package names

Solutions:

  1. Reload configuration:

    • Theme (theme.conf): Press Ctrl+R in Pacsea to explicitly reload theme colors and styling
    • Settings (settings.conf): Changes take effect automatically — no reload needed (settings are read fresh from disk)
    • Keybinds (keybinds.conf): Changes take effect automatically — no reload needed (keybinds are read fresh from disk)
    • For complete configuration documentation, see Configuration

  2. Check config file locations:

    ls -la ~/.config/pacsea/
# Should show: settings.conf, theme.conf, keybinds.conf

  3. Validate config syntax:

    • Ensure key = value format (spaces around =)
    • Check for typos in key names
    • Verify color formats: #RRGGBB or R,G,B (0-255)

  4. Reset to defaults:

    # Backup current config
cp -r ~/.config/pacsea ~/.config/pacsea.backup

# Remove config files (Pacsea will recreate defaults)
rm ~/.config/pacsea/settings.conf
rm ~/.config/pacsea/theme.conf
rm ~/.config/pacsea/keybinds.conf

# Restart Pacsea

  5. Check config file permissions:

    ls -l ~/.config/pacsea/*.conf
# Should be readable/writable by your user

  6. Package import validation: Enhanced input validation in import modals now provides better error messages for invalid package names. If importing packages fails:

    • Check that package names are valid (no special characters, proper format)
    • Ensure one package name per line in import files
    • Comments (lines starting with #) are automatically ignored
    • Invalid entries are now caught earlier with clearer error messages

  7. Theme file incomplete, empty, or colors fail at startup:

    • Current behavior: Before the first theme draw, Pacsea migrates legacy layouts when needed, then repairs the active theme file: missing palette colors are appended from built-in defaults; a missing or zero-byte file gets the full default skeleton. The path rules match normal loading (see Configuration and Startup: migration and automatic key completion).
    • Open theme.conf after a repair—you may see a trailing section starting with # Missing theme keys added automatically. You can edit those lines or replace them with your own theme; press Ctrl+R afterward to reload the theme in the TUI.
    • If problems continue, the file may contain duplicates, invalid colors, or permission issues. Check ls -l ~/.config/pacsea/theme.conf, free disk space, and run pacsea --verbose (or RUST_LOG=pacsea=debug pacsea) while reading ~/.config/pacsea/logs/pacsea.log. The config loader reports line numbers for parse errors—fix those manually; they are not auto-corrected.

Display/UI Issues

Symptoms:

  • UI doesn't render correctly
  • Colors look wrong
  • Terminal size issues
  • Mouse clicks not working

Solutions:

  1. Check terminal size:

    echo $COLUMNS $LINES
# Minimum recommended: 80x24

  2. Verify terminal supports required features:

    • True color support
    • Mouse reporting
    • Unicode characters

  3. Test with different terminal: Try running Pacsea in a different terminal emulator to isolate the issue.

  4. Check display server:

    echo $XDG_SESSION_TYPE  # Should show: wayland or x11

  5. For Wayland-specific issues:

    • Ensure wl-clipboard is installed for clipboard features
    • Some terminals may have limited mouse support

  6. For X11-specific issues:

    • Ensure xclip is installed for clipboard features
    • Verify X server is running: echo $DISPLAY

Performance Issues

Symptoms:

  • Slow search results
  • UI lag/freezing
  • High CPU/memory usage

Solutions:

  1. Clear cache:

    pacsea --clear-cache

  2. Check system resources:

    htop  # or: top

  3. Reduce search scope:

    • Use more specific search terms
    • Narrow results with repository chips in the Results title bar (core/extra/multilib/AUR and optional badges such as [BlackArch] when that repo is indexed)

  4. Disable unnecessary features: Edit ~/.config/pacsea/settings.conf:

    show_recent_pane = false
show_keybinds_footer = false

  5. Check network latency:

    ping aur.archlinux.org

Security Scan Issues

Symptoms:

  • Scans don't run
  • Scanner tools not found
  • VirusTotal API errors

Solutions:

  1. Install required scanner tools: Use the TUI Optional Deps modal (Options → Optional Deps) or install manually:

    sudo pacman -S clamav trivy semgrep-bin shellcheck

  2. Configure VirusTotal API key:

    • Open Optional Deps modal (Options → Optional Deps)
    • Navigate to "Security: VirusTotal API"
    • Press Enter to configure your API key
    • Or edit ~/.config/pacsea/settings.conf: 
      virustotal_api_key = your-api-key-here

  3. Verify scanner tools are in PATH:

    which clamscan trivy semgrep shellcheck

  4. Check scanner permissions: Some scanners may require specific permissions or database updates:

    sudo freshclam  # Update ClamAV database

Preflight Modal Issues

Symptoms:

  • Preflight modal doesn't appear
  • Can't access security scans
  • Modal blocks UI unexpectedly

Solutions:

  1. Enable Preflight modal: Edit ~/.config/pacsea/settings.conf:

    skip_preflight = false

    Changes to skip_preflight take effect automatically (settings are read fresh from disk). For theme changes, press Ctrl+R to reload. For details about the Preflight modal, see How to use Pacsea and Configuration.

  2. Modal navigation:

    • Use Tab/Shift+Tab to navigate
    • Press S to open Scan Configuration
    • Press Enter to confirm actions
    • Press Esc to cancel

  3. If modal blocks UI:

    • This is intentional to prevent accidental actions
    • Press Esc to close the modal
    • Complete or cancel the current operation first

System Update Dialog Issues

Symptoms:

  • Mirror update fails
  • Wrong mirror tool used
  • Update commands don't execute

Solutions:

  1. Verify distro detection: Pacsea auto-detects your distribution. Check detection:

    cat /etc/os-release

  2. Install correct mirror tool:

    • Arch: sudo pacman -S reflector
    • Manjaro: sudo pacman -S pacman-mirrors
    • EndeavourOS: sudo pacman -S eos-rankmirrors
    • CachyOS: sudo pacman -S cachyos-rate-mirrors

  3. Configure mirror settings: Edit ~/.config/pacsea/settings.conf:

    selected_countries = Switzerland, Germany, Austria
mirror_count = 20

  4. Test mirror tool manually:

    # Arch
sudo reflector --country Switzerland --latest 20 --protocol https --sort rate --save /etc/pacman.d/mirrorlist

# Manjaro
sudo pacman-mirrors --geoip

  5. Enhanced error handling: Pacsea now provides improved error messages and recovery for mirror index operations. If you encounter issues, check the logs for detailed error information:

    pacsea --verbose
# Check ~/.config/pacsea/logs/pacsea.log for mirror-related errors

Getting Help

If none of the above solutions resolve your issue:

  1. Gather diagnostic information:

    # Run with debug logging
pacsea --verbose > pacsea-output.txt 2>&1

# Collect system information
echo "=== System Info ===" > diagnostic.txt
uname -a >> diagnostic.txt
cat /etc/os-release >> diagnostic.txt
pacsea --version >> diagnostic.txt
echo "=== Warnings and Errors ===" >> diagnostic.txt
grep -iE "(warn|error)" ~/.config/pacsea/logs/pacsea.log >> diagnostic.txt
echo "=== Last 100 Log Lines ===" >> diagnostic.txt
tail -100 ~/.config/pacsea/logs/pacsea.log >> diagnostic.txt

  2. Check existing issues:

  3. Create a new issue:

    • Include the diagnostic information gathered above
    • Describe steps to reproduce
    • Mention what you've already tried

  4. For security issues:

Quick Reference: Debug Commands

# Enable debug logging
pacsea --verbose

# View live log output
tail -f ~/.config/pacsea/logs/pacsea.log

# Extract warnings and errors from logs
grep -iE "(warn|error)" ~/.config/pacsea/logs/pacsea.log

# Extract warnings/errors from recent logs only
tail -1000 ~/.config/pacsea/logs/pacsea.log | grep -iE "(warn|error)"

# Save warnings/errors to file
grep -iE "(warn|error)" ~/.config/pacsea/logs/pacsea.log > pacsea-errors-warnings.txt

# Clear cache
pacsea --clear-cache

# Check version
pacsea --version

# Test AUR connectivity
curl -I https://aur.archlinux.org

# Test terminal
which alacritty kitty xterm gnome-terminal

# Test sudo
sudo -v

# Check config files
ls -la ~/.config/pacsea/
cat ~/.config/pacsea/settings.conf

Clone this wiki locally