Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bouligo/cuterecon/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers common issues and their solutions.

​
Privileged scans

​
Permission denied when scanning

Nmap requires root privileges for certain scan types (SYN scans, OS detection, etc.). Solution: Configure a graphical sudo tool in settings (F10): 
/usr/bin/pkexec
Alternative tools:
  • kdesudo (KDE)
  • gksudo (GNOME)
  • sudo with -A flag for askpass

​
umask issues

If nmap XML files are created with incorrect permissions:
  1. Check your system umask: umask
  2. Ensure the nmap output directory has correct permissions
  3. Verify the graphical sudo tool preserves environment variables

​
Binary not found errors

​
Core binary not found

If you see “binary not found” errors: Symptom: 
Error: Binary '/usr/bin/nmap' not found
Solution:
  1. Open Settings (F10)
  2. Navigate to “Core binaries” tab
  3. Verify binary paths:
    • nmap: Usually /usr/bin/nmap
    • terminal: /usr/bin/konsole or /usr/bin/gnome-terminal
    • graphical su: /usr/bin/pkexec
  4. Check if binaries exist: 
which nmap
which konsole
which pkexec

​
User binary not executable

If a configured tool isn’t executable: Solution: 
# Check file permissions
ls -l /path/to/binary

# Make executable if needed
chmod +x /path/to/binary

​
Database issues

​
Database compatibility errors

Symptom: 
Error while importing database: incompatible schema
Solution: QtRecon includes automatic migrations for older database versions (< 1.2, < 1.6, < 1.7). If migration fails:
  1. Backup your database file
  2. Create a new database (Ctrl+N)
  3. Import your Nmap XML files (Ctrl+I)

​
Unsaved data warning

QtRecon tracks unsaved changes. If you see unexpected warnings: Solution:
  • Save your work regularly (Ctrl+S)
  • Enable autosave in Settings (F10) → User Preferences
  • Set autosave interval (default: 5 minutes)

​
XML parsing errors

​
Invalid Nmap XML

Symptom: 
Error parsing XML file
Causes:
  1. Incomplete scan: Nmap was interrupted mid-scan
  2. Corrupted file: File was modified or corrupted
  3. Wrong format: File is not a valid Nmap XML output
Solution:
  1. Ensure nmap completed successfully:
nmap -oX output.xml [target]
# Wait for scan to complete
  1. Validate XML syntax:
xmllint --noout output.xml
  1. Verify it’s Nmap output:
head -n 5 output.xml
# Should show: <?xml version="1.0"?>
# <!DOCTYPE nmaprun>

​
Missing XML files

Symptom: Nmap XML files disappear after scans. Cause: The remove_nmap_xml_files_after_scan option is enabled. Solution:
  1. Open Settings (F10)
  2. Navigate to “User Preferences”
  3. Uncheck “Remove Nmap XML files after scan”
  4. Click OK
With this option enabled, XML files are automatically deleted after being imported. Disable it if you need to keep the raw XML files.

​
Screenshot functionality

​
Screen lock detection issues

Symptom: Screenshots are taken even when screen is locked. Solution: Configure screen lock detection:
  1. Navigate to Screenshots tab in main window
  2. Enable “Don’t screenshot if screen is locked”
  3. Configure detection command:
For KDE/Plasma: 
dbus-send --session --dest=org.freedesktop.ScreenSaver --type=method_call --print-reply --reply-timeout=20000 /org/freedesktop/ScreenSaver org.freedesktop.ScreenSaver.GetActive
Expected result: boolean true For GNOME: 
gnome-screensaver-command -q
Expected result: The screensaver is active

​
Process tracking

Issue: Screenshot includes too many background processes. Solution: Configure process blacklist in conf.json: 
"screenshots": {
  "include_processes": true,
  "processes_blacklist": [
    "systemd",
    "dbus-daemon",
    "kwin_x11"
  ],
  "processes_ppid_blacklist": [1, 2]
}

​
Configuration issues

​
Invalid JSON in configuration

Symptom: 
Invalid configuration file: JSON decode error
Solution:
  1. Validate JSON syntax:
python3 -m json.tool ~/.config/qtrecon/conf.json
  1. If invalid, restore default configuration:
cd /path/to/qtrecon
cp conf.json.example ~/.config/qtrecon/conf.json
  1. Restart QtRecon

​
Configuration file not found

QtRecon looks for configuration in:
  1. $XDG_CONFIG_HOME/qtrecon/conf.json
  2. ~/.config/qtrecon/conf.json
If not found, it falls back to conf.json.example and creates a new configuration file.

​
Performance issues

​
High memory usage

Cause: Large in-memory database with many hosts/tabs. Solution:
  1. Close unused tabs regularly
  2. Save and restart QtRecon periodically
  3. Delete hosts with no services: File → Delete hosts with no services

​
Slow autosave

Solution:
  1. Open Settings (F10)
  2. Increase autosave interval
  3. Or disable autosave and save manually (Ctrl+S)

​
Getting help

If you encounter issues not covered here:
  1. Check the QtRecon repository for known issues
  2. Review configuration examples in conf.json.example
  3. Enable detailed logging to diagnose problems
  4. Report bugs with:
    • QtRecon version
    • Operating system
    • Configuration file (sanitized)
    • Error messages and logs

Build docs developers (and LLMs) love

Get started for freeTalk to us