# How to Report a Bug in GhostTrack: The Complete Guide for Contributors

> Learn to report a bug in GhostTrack by submitting a detailed GitHub issue. Follow our guide to provide all necessary information for a quick resolution.

- Repository: [K1LLU/GhostTrack](https://github.com/HunxByts/GhostTrack)
- Tags: how-to-guide
- Published: 2026-04-29

---

**To report a bug in GhostTrack, open a GitHub Issue on the HunxByts/GhostTrack repository and include the exact version from the README, your operating system, Python version, installed dependencies from [`requirements.txt`](https://github.com/HunxByts/GhostTrack/blob/main/requirements.txt), and the full traceback showing which function in [`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py) failed.**

GhostTrack is a lightweight Python CLI tool that bundles OSINT utilities including IP lookup, phone number validation, and username enumeration across social platforms. When you encounter crashes or unexpected behavior in functions like `IP_Track()` or `TrackLu()`, submitting a structured bug report accelerates the debugging process. This guide shows exactly how to report a bug in GhostTrack by referencing the actual source code structure and required diagnostic information.

## Required Information for Bug Reports

Effective bug reports for GhostTrack require specific technical details to reproduce failures. The maintainer needs these data points to trace issues back to the relevant code paths in [`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py).

### Version and Environment Details

Always provide the following system information:

- **Exact version** – Copy the version string from the README (e.g., "Version 2.2")
- **Operating system** – Specify Linux distribution, Termux, or Windows version
- **Python interpreter** – Run `python3 --version` and report the output
- **Installation method** – Note whether you cloned the repository, used the Linux `.deb` package, or installed manually

### Dependency Verification

GhostTrack relies on third-party packages listed in **[`requirements.txt`](https://github.com/HunxByts/GhostTrack/blob/main/requirements.txt)**, specifically `requests` and `phonenumbers`. Include the output of `pip3 freeze` to confirm exact package versions, as API compatibility issues often stem from dependency mismatches.

### Error Output and Reproduction Steps

Document the failure with precision:

- The **full Python traceback** showing the exception type and line number in [`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py)
- The **menu option selected** during execution
- The **exact input values** provided (e.g., IP addresses or usernames)
- **Network conditions** – Note if you were offline or behind a proxy, since the tool queries external APIs

## Step-by-Step Bug Reporting Process

Follow this structured workflow to ensure your issue gets triaged quickly:

1. **Navigate to Issues** – Go to the [HunxByts/GhostTrack Issues](https://github.com/HunxByts/GhostTrack/issues) page and click *New issue*.
2. **Select Template** – Use the bug report template if available; otherwise, start with a clear title format: `Bug: [FunctionName] crashes on [condition]`.
3. **Complete All Sections**:
   - **Description** – Concise summary of the malfunction
   - **Version** – Paste the version string from [`README.md`](https://github.com/HunxByts/GhostTrack/blob/main/README.md)
   - **Environment** – OS, Python version, and installation method
   - **Steps to Reproduce** – Numbered list from launch to crash (e.g., 1. `python3 GhostTR.py`, 2. Select *IP Tracker*, 3. Enter `256.0.0.1`)
   - **Expected vs. Actual Result** – Describe intended behavior and paste the complete console output
4. **Attach Supporting Files** – Include diffs if you modified the code, or screenshots of the error output.
5. **Submit** – Post the issue to notify the maintainer.

## Common Bug Patterns in GhostTR.py

Understanding the architecture helps identify where bugs occur. The main script **[`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py)** contains four primary feature functions that are frequent sources of errors:

### Network-Dependent Failures

Most bugs stem from API interactions without proper error handling. The **`IP_Track()`** function (lines 39-78) queries `ipwho.is`, while **`TrackLu()`** (lines 121-167) iterates through social media URLs. If these endpoints return non-200 status codes or malformed JSON, the script raises unhandled exceptions.

### Input Validation Errors

Functions like **`phoneGW()`** (lines 80-119) process raw user input without extensive sanitization. Invalid IPv4 addresses (e.g., `256.0.0.1`) or malformed phone numbers trigger `KeyError` or `json.JSONDecodeError` exceptions when the code attempts to parse the API response.

## Capturing Debug Information for Your Report

Use these terminal commands to generate copy-paste content that helps maintainers reproduce your environment:

Capture system details:

```bash
uname -a
python3 --version
pip3 freeze | grep -E 'requests|phonenumbers'

```

Reproduce and capture the error:

```bash
git clone https://github.com/HunxByts/GhostTrack.git
cd GhostTrack
pip3 install -r requirements.txt
python3 GhostTR.py <<EOF
1
256.0.0.1
EOF

```

Paste the resulting traceback verbatim into your issue, ensuring it includes references to specific line numbers in [`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py) (e.g., `File "GhostTR.py", line 46, in IP_Track`).

## Key Source Files to Reference

When describing bugs, cite these specific files and locations to demonstrate technical accuracy:

- **[`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py)** – Main executable containing `IP_Track()`, `phoneGW()`, `TrackLu()`, and menu infrastructure (lines 39-167)
- **[`requirements.txt`](https://github.com/HunxByts/GhostTrack/blob/main/requirements.txt)** – Dependency manifest listing `requests` and `phonenumbers`
- **[`README.md`](https://github.com/HunxByts/GhostTrack/blob/main/README.md)** – Contains version badge and platform-specific installation instructions

By linking directly to line ranges in [`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py) (such as lines 39-78 for IP tracking logic), you provide maintainers with precise navigation points to the problematic code.

## Summary

- **Report bugs via GitHub Issues** on the HunxByts/GhostTrack repository using descriptive titles that mention the affected function.
- **Always include environment data**: Version string, OS, Python version, and the output of `pip3 freeze`.
- **Provide full tracebacks** that point to specific functions and line numbers in [`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py).
- **Document network conditions** since GhostTrack relies on external APIs (`ipwho.is`, `api.ipify.org`, social media endpoints).
- **Attach reproduction scripts** or exact input sequences that trigger the failure.

## Frequently Asked Questions

### Where do I report bugs in GhostTrack?

Navigate to the [Issues section](https://github.com/HunxByts/GhostTrack/issues) of the GitHub repository and create a new issue. Format your title as `Bug: [function_name] - [brief description]` to help maintainers quickly identify the relevant code block in [`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py).

### What Python version does GhostTrack require?

GhostTrack requires **Python 3**. Verify your installation by running `python3 --version` before reporting environment-specific bugs, as syntax or library differences between Python versions can cause compatibility issues.

### Why does GhostTrack crash when I lose internet connectivity?

The functions `IP_Track()`, `showIP()`, and `TrackLu()` depend on external web APIs. When offline, the `requests` library fails to establish connections or receives empty responses, causing unhandled exceptions during JSON parsing. Include your network status in bug reports involving these functions.

### How do I identify which function caused the error?

Examine the **traceback** in your terminal output. The error message specifies the function name and line number in [`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py) (for example, `File "GhostTR.py", line 46, in IP_Track`), allowing you to reference the exact implementation in your bug report and help maintainers locate the bug immediately.