Troubleshooting & Bug Reporting
Relevant source files
The following files were used as context for generating this wiki page:
Troubleshooting and bug reporting in Quickemu are structured around a set of diagnostic tools and community-driven support channels. As a Bash-based wrapper for QEMU, the project provides specific utilities to validate environment configurations, download integrity, and system compatibility to ensure that virtual machines run with optimized hardware detection.
The process involves utilizing built-in diagnostic scripts like quickreport and chunkcheck, participating in community discussions, and following strict contribution guidelines when submitting issues or pull requests to the repository.
Diagnostic Utilities
Quickemu includes dedicated scripts designed to identify issues within the host environment or during the OS acquisition phase. These tools are the first line of defense when a virtual machine fails to launch or an ISO fails to download correctly.
System Diagnostics with quickreport
The quickreport utility is a Bash-based system diagnostics tool. It is intended to gather relevant system information that can be used to debug environmental issues or hardware incompatibilities.
Sources: AGENTS.md:12, AGENTS.md:15
Download Verification with chunkcheck
When using quickget to download operating system images, the chunkcheck utility is used to verify the integrity of the downloaded data. This ensures that corruption during the download process is not the cause of VM boot failures.
Sources: AGENTS.md:13, AGENTS.md:16
Validation Logic Flow
The following diagram illustrates the recommended troubleshooting flow when encountering issues with VM creation or execution:
The diagram shows how chunkcheck and quickreport serve as primary diagnostic steps before engaging with the community or filing reports.
Sources: AGENTS.md:12-16, CONTRIBUTING.md:4-10
Bug Reporting and Support Channels
Quickemu relies on GitHub-based workflows for tracking issues and providing user support. Users are encouraged to utilize different channels based on the nature of their query.
| Channel | Purpose |
|---|---|
| Quickemu Discussions | General questions and community support. |
| Quickemu Issues | Filing formal bug reports and feature requests. |
| Discord (#quickemu) | Real-time interaction and reporting Code of Conduct violations. |
| GitHub Sponsors | Financial support for the project maintainers. |
Sources: CONTRIBUTING.md:4-13, CODE_OF_CONDUCT.md:58-60
Security Vulnerabilities
Security-specific issues follow a distinct path. Users who discover vulnerabilities should not file a standard public bug report but instead use the "Report a vulnerability" feature within the GitHub Issues interface. The project supports the current major version (4.9.x) with security updates on a best-efforts basis.
Sources: SECURITY.md:5-15
Development and Testing for Contributors
For developers looking to fix reported bugs, Quickemu provides a specific environment and a set of testing commands to validate changes before submission.
Testing quickget
Since quickget handles complex logic for nearly 1000 OS editions, contributors must test URL construction and architecture support.
# Test quickget URLs for a specific OS
./quickget --check <os> [release] [edition]
# Test ARM64 downloads
./quickget --arch arm64 --check <os> [release] [edition]
# Test all supported architectures
./quickget --check-all-arch <os> [release] [edition]
Sources: AGENTS.md:28-32, README.md:54
CI and Linting
Before submitting a bug fix, scripts must pass ShellCheck and match the project's formatting standards (2-space indent for quickemu, 4-space for quickget).
The sequence diagram outlines the verification steps required for any code contribution intended to fix a bug.
Sources: AGENTS.md:37-43, AGENTS.md:73-80
Summary
Troubleshooting Quickemu involves a combination of local diagnostics using quickreport and chunkcheck, followed by community engagement via Discussions or Discord. When a definitive bug is identified, it is reported through GitHub Issues, and contributors must follow a strict testing and linting regimen—including Conventional Commits and ShellCheck compliance—to ensure high-quality fixes are integrated into the project.
Sources: AGENTS.md:37-80, CONTRIBUTING.md:1-13