# How to Report a Bug in Vorssaint-Utils: Step-by-Step Guide > Learn how to report a bug in Vorssaint-Utils using our GitHub issue template. Follow our troubleshooting guide and checklist for efficient bug reporting. - Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils) - Tags: how-to-guide - Published: 2026-09-13 --- **To report a bug in Vorssaint-Utils, use the structured GitHub issue template at [`/.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/vorssaint/vorssaint-utils/blob/main//.github/ISSUE_TEMPLATE/bug_report.yml) after verifying macOS permissions via [`docs/TROUBLESHOOTING.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/docs/TROUBLESHOOTING.md) and completing the mandatory pre-flight checklist.** Reporting bugs effectively ensures maintainers can reproduce and fix issues quickly. In the `vorssaint/vorssaint-utils` repository, the maintainers enforce a rigorous workflow that filters out configuration errors and captures essential diagnostic data upfront. This guide walks through the exact steps required to submit a valid, actionable bug report for the Vorssaint macOS utility. ## Check the Troubleshooting Guide First Before opening a new issue, consult [`docs/TROUBLESHOOTING.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/docs/TROUBLESHOOTING.md) in the repository root. This document explains common scenarios where the app appears broken but actually lacks proper system authorization. According to the source documentation, the troubleshooting guide covers how to verify that Vorssaint is correctly granted Accessibility, Screen Recording, System Audio Recording, or Automation permissions. Many apparent bugs are simply permission denials that can be resolved without code changes. ### Resetting Permissions If a feature does nothing at all, the guide recommends checking System Settings → Privacy & Security to confirm Vorssaint is listed and enabled for the required permission, then toggling it off and back on. If the issue persists after verification, you may need to run [`Tools/uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/uninstall.sh) for a complete removal and fresh install, which clears cached permission states that macOS sometimes fails to refresh. ## Use the GitHub Issue Template The repository provides a dedicated bug report form defined in [`/.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/vorssaint/vorssaint-utils/blob/main//.github/ISSUE_TEMPLATE/bug_report.yml). When you navigate to Issues → New Issue → 🐛 Bug Report on GitHub, the interface renders this YAML template into a structured web form with mandatory fields. This template enforces data quality by requiring specific inputs before the submit button activates, ensuring every report contains the diagnostic information found in the "Reporting a useful bug" section of the troubleshooting guide. ### Complete the Pre-Flight Checklist The template requires you to confirm two prerequisites via checkboxes: - **Permission verification**: You have checked that Vorssaint is listed and switched on for the permission it needs in System Settings, and you have toggled it off and back on. - **Latest version**: You have confirmed the problem still occurs on the latest released version of Vorssaint. These checkpoints eliminate false-positive reports caused by misconfigured Accessibility access or outdated builds. ## Provide Required Bug Details The template captures structured data designed to make reports immediately actionable without follow-up questions. ### Describe the Bug and Reproduction Steps You must provide: - **Description**: A clear explanation of expected behavior versus actual behavior. - **Reproduction steps**: A numbered list starting from application launch. - **Feature area**: Categorical selection (e.g., "Windows and Dock", "Sound", "Keyboard"). - **Screenshots or recordings**: Visual evidence is optional but highly recommended for UI-related issues. ### Specify Environment Information The form requires exact version information to isolate platform-specific bugs: - **Vorssaint Version**: Found in Settings → About. - **macOS Version**: Selected from a dropdown (e.g., macOS 14 Sonoma). - **Hardware configuration**: Mac model and display setup. - **Installation method**: Homebrew, direct download, or built from source. ## Submit the Issue and Attach Diagnostics Once all required fields are populated, click **Submit new issue**. The template automatically applies the `bug` label and formats the content according to the repository's triage standards. ### Special Case: Source Builds If you compiled Vorssaint from source, attach the output of the self-test command to your report: ```bash ./build/Vorssaint --selftest ``` This provides a health snapshot of your specific build environment, which is particularly valuable when debugging startup behavior in [`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift) or build-specific linking issues. ## Example Bug Report Below is a filled-in example that mirrors the template structure. Use this as a reference when completing the GitHub form: ```markdown - [x] If the feature does nothing at all, I checked that Vorssaint is listed and switched on for the permission it needs in System Settings, Privacy and Security, and toggled it off and back on. - [x] It still happens on the latest version. ## Description When I click the **Window Layout** shortcut *⌃⌘L*, nothing happens. I expect the active window to snap to the left half of the screen. ## Steps to Reproduce 1. Open Vorssaint. 2. Press **⌃⌘L** (the default "snap left" shortcut). 3. Observe that the window does not move. ## Feature Area - Windows and Dock ## Screenshots / Recordings *(attach a short screen recording showing the shortcut being pressed with no effect)* ## Vorssaint Version 3.1.4 ## macOS Version macOS 14 (Sonoma) ## Language English ## Mac and Displays MacBook Pro 14 (M3 Pro) · built‑in + one 4K external, scaled, two Spaces ## Installation Method Homebrew ``` ## Summary - Always consult [`docs/TROUBLESHOOTING.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/docs/TROUBLESHOOTING.md) for permission issues before filing a bug. - Use the structured template at [`/.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/vorssaint/vorssaint-utils/blob/main//.github/ISSUE_TEMPLATE/bug_report.yml) to ensure consistent data capture. - Complete the pre-flight checklist confirming permissions and version currency. - Provide specific reproduction steps, exact version numbers from Settings → About, and installation method. - For source builds, include `./build/Vorssaint --selftest` output to aid debugging. ## Frequently Asked Questions ### What if I don't have a GitHub account? You must create a free GitHub account to access the issue tracker in the `vorssaint/vorssaint-utils` repository. The maintainers centralize all technical discussion in GitHub Issues to ensure searchable history and proper integration with the [`/.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/vorssaint/vorssaint-utils/blob/main//.github/ISSUE_TEMPLATE/bug_report.yml) workflow. ### Why does the template require toggling permissions off and on? The [`docs/TROUBLESHOOTING.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/docs/TROUBLESHOOTING.md) documentation indicates that macOS sometimes fails to correctly register permission grants until the toggle is cycled. This step, described in the pre-flight checklist, eliminates the majority of false-positive bug reports related to Accessibility or Screen Recording access. ### Can I report a bug for an older version of Vorssaint? No. The pre-flight checklist explicitly requires confirming the bug exists on the latest version. The maintainers only investigate issues reproducible in current releases. Update to the latest version via Homebrew or the project's releases page before submitting. ### Where do I find the version number for the bug report? Open the Vorssaint application, navigate to Settings → About, and copy the version string displayed there. If you built from source, you can also run `./build/Vorssaint --selftest` to output build metadata including the commit hash and version string.