Skip to main content

​
Troubleshooting Guide

This guide covers common issues you may encounter when installing or running HackingTool and their solutions.

​
Installation Issues

​
Root Permission Required

HackingTool must be run as root. If you see permission errors, ensure you’re using sudo.
Error: This installer must be run as root Solution: 
sudo python3 install.py
Or for manual installation: 
sudo hackingtool

​
Internet Connection Errors

Error: Internet connection not available The installer checks connectivity to both Google and GitHub. If you see this error:
  1. Verify your internet connection: 
    ping -c 4 google.com
  2. Check if you can reach GitHub: 
    curl -I https://github.com
  3. If you’re behind a proxy, configure git: 
    git config --global http.proxy http://proxy.example.com:8080
git config --global https.proxy https://proxy.example.com:8080

​
Git Clone Failures

Error: Failed to clone repository Common causes:
  • Network connectivity issues
  • Firewall blocking git protocol
  • Disk space issues
Solutions:
If automatic cloning fails, try manual installation:
# Clone the repository manually
git clone https://github.com/Z4nzu/hackingtool.git
cd hackingtool

# Set proper permissions
chmod -R 755 .

# Run the installer
sudo python3 install.py

​
Dependency Issues

​
Python Version Compatibility

HackingTool requires Python 3.x. Python 2.7 is not supported.
Check your Python version: 
python3 --version
If Python 3 is not installed: Kali/Debian/Ubuntu: 
sudo apt-get update
sudo apt-get install python3 python3-pip python3-venv
Arch Linux: 
sudo pacman -S python python-pip

​
Missing System Dependencies

Error: apt-get install failed or package installation errors Required packages:
  • git
  • python3-pip
  • python3-venv
  • figlet
  • boxes
  • php
  • curl
  • xdotool
  • wget
For Kali Linux / Parrot OS / Debian / Ubuntu:
sudo apt-get update
sudo apt-get install -y git python3-pip python3-venv figlet boxes php curl xdotool wget
For Arch Linux:
sudo pacman -Syu
sudo pacman -S --noconfirm git python-pip figlet
On Arch Linux, figlet may need to be installed from AUR if not available in official repos.

​
Python Package Installation Failures

Error: Issues installing requirements from requirements.txt The project requires these Python packages:
  • boxes
  • flask
  • lolcat
  • requests
  • rich
Manual installation: 
pip3 install boxes flask lolcat requests rich
If pip is not working: 
# Upgrade pip
python3 -m pip install --upgrade pip

# Install with user flag if permission denied
pip3 install --user boxes flask lolcat requests rich

​
Platform-Specific Issues

​
Kali Linux vs Arch Linux

The installer prompts you to select your distribution: 
[1] Kali / Parrot (apt)
[2] Arch Linux (pacman)
[0] Exit
Select the correct option for your distribution. Using the wrong package manager will cause installation failures.
Issue: Package manager conflictsSolution:
# Update package lists
sudo apt-get update

# Fix broken dependencies
sudo apt-get install -f

# Reconfigure dpkg if needed
sudo dpkg --configure -a
Issue: figlet not found in pacmanSolution: Install from AUR:
git clone https://aur.archlinux.org/figlet.git
cd figlet
makepkg -si
Or use an AUR helper:
yay -S figlet
# or
paru -S figlet

​
Parrot OS Specifics

Parrot OS uses apt like Kali, so select option [1] during installation.
Parrot OS is fully compatible with HackingTool. Use the same troubleshooting steps as Kali Linux.

​
Tool Installation Failures

​
Individual Tool Installation Errors

When installing individual hacking tools through the menu, you may encounter: Error: Tool clone or installation fails
  1. Repository no longer available
    • Some tool repositories may be moved or deleted
    • Check the project URL in the tool description
    • Look for forks or alternative repositories
  2. Dependencies missing for specific tools
    • Read the tool’s README for specific requirements
    • Install tool-specific dependencies manually
  3. Permission issues during tool installation 
    # Ensure hackingtool is run with sudo
sudo hackingtool

​
Tool Won’t Run After Installation

Issue: Tool installed successfully but won’t execute Debugging steps: 
# Check if tool binary exists
which <tool-name>

# Check PATH
echo $PATH

# Try running with full path
/usr/share/hackingtool/tools/<tool-name>

​
Path Configuration Issues

​
HackingTool Command Not Found

Error: hackingtool: command not found Solution:
The installer should create a launcher at /usr/bin/hackingtool. If it’s missing:
# Check if the binary exists
ls -la /usr/bin/hackingtool

# If missing, run the installer again
cd /path/to/hackingtool
sudo python3 install.py

# Or create a manual symlink
sudo ln -s /usr/share/hackingtool/hackingtool.sh /usr/bin/hackingtool
Verify the installation:
which hackingtool
# Should output: /usr/bin/hackingtool

​
Virtual Environment Issues

Error: Virtual environment not activated properly The installer creates a virtual environment at /usr/share/hackingtool/venv Manual activation: 
cd /usr/share/hackingtool
source venv/bin/activate
python3 hackingtool.py

​
Runtime Errors

​
ImportError or ModuleNotFoundError

Error: ModuleNotFoundError: No module named 'rich' (or other modules) Solution: 
# Activate the virtual environment
cd /usr/share/hackingtool
source venv/bin/activate

# Install requirements
pip install -r requirements.txt

# Or install missing module directly
pip install rich

​
Permission Denied Errors

Error: Permission denied when running tools
Most penetration testing tools require root privileges. Always run HackingTool with sudo.
sudo hackingtool

​
Directory Already Exists

Error: The directory /usr/share/hackingtool already exists The installer will prompt you to replace it. If you want to keep your existing installation: 
# Backup your current installation
sudo mv /usr/share/hackingtool /usr/share/hackingtool.backup

# Then run the installer
sudo python3 install.py

​
Docker-Specific Issues

​
Build Errors

Error: Docker build fails
# Check Docker daemon is running
sudo systemctl status docker

# Start Docker if needed
sudo systemctl start docker

# Build the image
docker build -t vgpastor/hackingtool .

​
Container Won’t Start

# Check container status
docker ps -a

# View container logs
docker logs hackingtool

# Start with docker-compose
docker-compose up -d

​
Cannot Access Container

# Exec into running container
docker exec -it hackingtool bash

# If container is not running, start it first
docker start hackingtool
docker exec -it hackingtool bash

​
Getting Help

If you encounter issues not covered here:
  1. Check existing issues: GitHub Issues
  2. Create a bug report: Use the bug report template at .github/ISSUE_TEMPLATE/bug_report.md
  3. Include this information:
    • Operating system and version
    • Python version (python3 --version)
    • Installation method (manual, Docker)
    • Full error message
    • Steps to reproduce
  4. Provide system information: 
    # OS info
cat /etc/os-release

# Python version
python3 --version

# Installed packages
pip3 list
Before reporting an issue, try running the installation again with a clean environment. Many issues are resolved by removing the old installation and reinstalling.

​
Quick Fixes Checklist

Before diving deep into troubleshooting, try these quick fixes:
  • Run with sudo
  • Update system packages (apt update or pacman -Syu)
  • Verify internet connection
  • Check Python 3 is installed
  • Ensure all dependencies are installed
  • Remove and reinstall HackingTool
  • Check disk space (df -h)
  • Review error messages carefully

Build docs developers (and LLMs) love

Get started for freeTalk to us