# How to Report a Bug in user-scanner: A Complete Guide

> Learn how to report a bug in user-scanner effectively. Follow our guide for submitting detailed reports on GitHub issues to help improve the tool.

- Repository: [Kaif/user-scanner](https://github.com/kaifcodec/user-scanner)
- Tags: how-to-guide
- Published: 2026-08-30

---

**To report a bug in user-scanner, search existing GitHub issues first, then submit a detailed report including your version from [`user_scanner/version.json`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/version.json), environment details, the exact CLI command used, and a minimal reproducible example.**

When you encounter unexpected behavior in **user-scanner**, the open-source username enumeration tool maintained in the **kaifcodec/user-scanner** repository, providing structured information helps maintainers reproduce and fix issues quickly. The project follows a standard GitHub workflow where detailed bug reports significantly reduce triage time and improve resolution speed.

## Search Existing Issues Before Reporting

Before opening a new issue, browse the [GitHub Issues page](https://github.com/kaifcodec/user-scanner/issues) to check if your bug has already been reported. Duplicate reports fragment discussion and slow down the debugging process.

If you find an existing report that matches your issue, add additional context as a comment rather than opening a new ticket. Include any unique details about your environment or error output, and up-vote the existing issue to signal its impact.

## Gather Essential Debugging Information

A high-quality bug report requires specific technical details extracted from your local environment. The maintainers need this data to trace execution paths in [`user_scanner/core/result.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/result.py) and verify version-specific behavior.

### Capture the Version String

Include the exact version number stored in [`user_scanner/version.json`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/version.json). This file contains the current release identifier (e.g., `1.5.1.1`) that helps maintainers identify if the bug exists in a specific release.

```bash
cat user_scanner/version.json

```

When reporting, paste the full version string verbatim to eliminate ambiguity about which code revision you are running.

### Document Your Environment

Specify your operating system, Python version, and installation method. Run `python --version` in your terminal and note whether you installed via PyPI, Nix, or a virtual environment.

Network configuration details also matter. Indicate whether you are using proxies, VPNs, or operating behind restricted network topology, as these factors affect how the scanner interacts with target platforms.

### Record the CLI Invocation and Output

Provide the exact command you executed, including all flags. For example:

```bash
user-scanner -u johndoe --cross-scan -c social

```

If the program crashes, include the complete traceback. For logic errors where the program completes but returns incorrect results (such as `Result.taken` when the account does not exist), paste the relevant portion of the output. The `Result` object defined in [`user_scanner/core/result.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/result.py) uses states like `Result.available` and `Result.taken`, so reference these specific return values in your description.

### Create a Minimal Reproducible Example

Isolate the failure to the smallest possible input. A single-username scan that consistently triggers the bug is more valuable than a complex batch operation. For instance:

```bash
user-scanner -u nonexistent_user -c dev --cross-scan

```

This stripped-down command eliminates variables and gives maintainers a reliable test case.

## Submitting the Bug Report

Once you have compiled the required information, submit your report through GitHub using either the web interface or the command-line tool.

### Using the GitHub Web Interface

Navigate to the repository and click **"New issue"**. Select the **Bug report** template if available, and fill in all sections with the data gathered above. Reference the documentation in [`CONTRIBUTING.md`](https://github.com/kaifcodec/user-scanner/blob/main/CONTRIBUTING.md) for specific formatting guidelines required by the project.

Structure your report with clear sections for version, OS/Python details, observed behavior versus expected behavior (e.g., expecting `Result.available` but receiving `Result.taken`), reproducible steps, and additional context.

### Using the GitHub CLI (Alternative)

If you have the GitHub CLI (`gh`) installed, you can create the issue directly from your terminal. This method ensures consistent labeling and formatting:

```bash
gh issue create \
  --title "Bug: Email scan misclassifies valid address on example.com" \
  --body "$(cat <<'EOF'
**Version**: 1.5.1.1
**OS / Python**: Linux / Python 3.12.0
**Command**: user-scanner -e alice@example.com -c social
**Observed behavior**: `Result.taken` returned, but the email does not exist on the site.
**Expected behavior**: `Result.available`.
**Steps to reproduce**
1. Run the command above.
2. Observe the output.
**Additional info**
- No proxies enabled.
- Network connection is stable.
EOF
)" \
  --label "bug"

```

The `--label "bug"` tag automatically categorizes the issue for triage. For complex reports involving specific flag interactions, consult [`docs/FLAGS.md`](https://github.com/kaifcodec/user-scanner/blob/main/docs/FLAGS.md) to ensure you describe the exact CLI options used.

## Following Up and Next Steps

After submission, monitor the issue for maintainer responses. They may request additional logs, ask you to test against the `tests/` directory to isolate regressions, or suggest workarounds such as disabling specific flags.

If the maintainers need deeper debugging, they might reference [`user_scanner/core/result.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/result.py) or ask you to run the test suite locally. Keep your environment available for follow-up questions to expedite the fix.

## Summary

- **Search first**: Check existing issues on the kaifcodec/user-scanner GitHub repository before creating duplicates.
- **Version is critical**: Always include the exact string from [`user_scanner/version.json`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/version.json).
- **Be specific**: Document your OS, Python version, exact CLI command, and network configuration.
- **Show don't tell**: Provide full tracebacks or output showing `Result.taken` vs `Result.available` states defined in [`user_scanner/core/result.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/result.py).
- **Minimize reproduction**: Create the smallest possible command that triggers the bug.
- **Use templates**: Submit via GitHub web UI or the `gh` CLI with the `bug` label as outlined in [`CONTRIBUTING.md`](https://github.com/kaifcodec/user-scanner/blob/main/CONTRIBUTING.md).
- **Stay engaged**: Respond to maintainer requests for additional testing or logs.

## Frequently Asked Questions

### Where do I find the current version of user-scanner?

The current release version is stored in [`user_scanner/version.json`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/version.json) in the repository root. Run `cat user_scanner/version.json` to display the version string (e.g., `1.5.1.1`), which is essential for diagnosing version-specific bugs according to the kaifcodec/user-scanner source code.

### What information is most important when reporting a bug?

The most critical details are the version from [`user_scanner/version.json`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/version.json), your exact CLI invocation (including all flags documented in [`docs/FLAGS.md`](https://github.com/kaifcodec/user-scanner/blob/main/docs/FLAGS.md)), the complete error traceback or output showing `Result` object states, and a minimal reproducible example. This information allows maintainers to trace execution through [`user_scanner/core/result.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/result.py).

### Can I report bugs using the command line?

Yes. If you have the GitHub CLI (`gh`) installed, you can use `gh issue create` with the `--label "bug"` flag to submit reports directly from the terminal. This method supports multi-line body text and automatically applies the bug label for faster triage.

### What should I do if my bug report is ignored?

Wait at least one week for a response, as maintainers may be coordinating fixes against the `tests/` directory or analyzing edge cases in the `Result` object logic. If the issue remains unattended, add a polite comment with additional context or logs rather than opening a duplicate issue.