# Known Issues with Vorssaint-Utils: Common Problems and Fixes > Discover known issues with vorssaint-utils including macOS privacy, Gatekeeper, and UI freezes. Find solutions and troubleshooting steps in the official repository. - Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils) - Tags: known-issues - Published: 2026-09-13 --- **Yes, known issues with vorssaint-utils primarily involve macOS privacy permissions, Gatekeeper warnings, and occasional UI freezes, most of which are resolved through specific troubleshooting steps documented in the repository.** Vorssaint-utils is a Swift-based macOS menu-bar application that bundles dozens of independent utilities—including a volume mixer, app switcher, and screen capture tools—each enabled through feature flags. Because the app's functionality is tightly coupled to macOS privacy permissions, many known issues with vorssaint-utils stem from permission handling or edge-case bugs in the Accessibility and Screen Recording APIs, as tracked in [`docs/TROUBLESHOOTING.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/docs/TROUBLESHOOTING.md) and [`CHANGELOG.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/CHANGELOG.md). ## Permission and Security Issues Most functional failures trace back to macOS privacy controls and code signing verification handled in [`Sources/Vorssaint/Core/Permissions.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/Permissions.swift) and [`Sources/Vorssaint/App/AppDelegate.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/App/AppDelegate.swift). ### Gatekeeper and Code Signature Warnings When launching vorssaint-utils, macOS may refuse to start the app or display a Gatekeeper warning. This occurs because the operating system verifies the code signature and notarization of the binary, which is managed in [`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift) during the build process. The README documents the workaround: right-click the app and select **Open** to bypass the warning for unsigned local builds. ### Privacy Permissions Not Sticking A common issue involves toggling permissions in System Settings that appear to have no effect or revert after relaunch. This happens because macOS caches the old signature, and the permission watcher in [`Sources/Vorssaint/Core/Permissions.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/Permissions.swift) does not automatically refresh after signature changes. To resolve this, remove the old entry from System Settings and re-grant the permission, or reset the permission cache using `tccutil`. ### Silent Feature Failures When a utility such as **Window Layout** or **Dock Preview** shows no effect, the root cause is typically a missing privacy permission. The app polls permission states on launch, but if Accessibility or Screen Recording access is denied, the feature silently fails. The troubleshooting guide lists exact permission checks and recovery steps for each utility. ## Functional Bugs and Performance Regressions Recent releases have addressed several architectural edge cases documented in the CHANGELOG. ### App Switcher Freezes and High CPU Historically, the app switcher queried the Accessibility API for every window on each activation, causing high CPU usage and hangs when encountering slow applications. The recent refactor in [`Sources/Vorssaint/App/AppDelegate.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/App/AppDelegate.swift) and related switcher modules adds caching for window lists and skips hidden helper windows, resolving the freeze issues noted in CHANGELOG entries #28-30. ### Dock Preview Disappearances Dock thumbnails that revert to app icons or disappear entirely indicate missing Screen Recording permissions, which prevent the app from capturing live window content. This was fixed in version 3.3.5, where the switcher now retries capture after the permission is granted (see CHANGELOG #40-42). ### Screen Recording Audio-Video Sync Issues Earlier versions of the screen recorder suffered from audio and video drift when pausing and resuming captures. The root cause was the separation of audio tracks in the capture pipeline. The code in [`Sources/Vorssaint/Core/RecorderStrings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/RecorderStrings.swift) now synchronizes streams during recording, correcting the alignment issues detailed in CHANGELOG #21-23. ### Memory Leaks from Event Listeners Toggling multiple features on and off could cause high CPU or memory usage because each utility registered its own event listeners without deregistering them when disabled. Recent releases added automatic listener cleanup in the core event handling logic, preventing the leaks described in CHANGELOG #51-55. ## Installation and Uninstallation Artifacts Removing vorssaint-utils sometimes leaves behind settings, login items, or permission grants that affect future reinstalls. ### Incomplete Uninstall Leaving Traces Prior fixes addressed uninstall scripts that failed to remove the launch agent, preferences, or TCC permissions. The current [`Tools/uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/uninstall.sh) script fully removes all traces by deleting the launch agent, preference files, and running `tccutil reset` for the bundle ID `com.vorssaint.utils`, as documented in TROUBLESHOOTING sections #67-79. ## Diagnostic Commands and Recovery Steps Run these commands from the repository root to diagnose or resolve the known issues with vorssaint-utils. Run the built-in self-test to generate a health summary for bug reports: ```bash ./build/Vorssaint --selftest ``` Reset all macOS privacy permissions for the app when permissions "won't stick": ```bash tccutil reset All com.vorssaint.utils ``` Reset only the Accessibility permission if that specific access is problematic: ```bash tccutil reset Accessibility com.vorssaint.utils ``` Perform a clean uninstall that removes the app, launch agent, preferences, and permissions: ```bash ./Tools/uninstall.sh ``` Build the app from source to verify code signing and permissions locally: ```bash git clone https://github.com/vorssaint/vorssaint-utils.git cd vorssaint-utils ./build.sh ./build.sh --install ``` ## Summary - **Gatekeeper warnings** occur with unsigned builds; use the right-click Open workaround or build from source via [`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift). - **Permission-related failures** are the most common cause of non-functional features; verify Accessibility and Screen Recording access in System Settings. - **Sticky permissions** require resetting the TCC database with `tccutil reset` when macOS caches old signatures. - **App Switcher freezes** were resolved by adding window caching and filtering hidden helpers. - **Screen recording drift** was fixed by synchronizing audio-video streams in [`RecorderStrings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/RecorderStrings.swift). - **Complete uninstallation** requires [`Tools/uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/uninstall.sh) to remove launch agents and reset permissions. ## Frequently Asked Questions ### How do I fix Gatekeeper warnings when opening vorssaint-utils? When macOS displays a security warning preventing the app from opening, right-click the application bundle and select **Open** to bypass the code signature check. For permanent resolution, build the signed bundle from source using [`./build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/./build.sh), which creates a properly notarized binary recognized by [`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift) configuration. ### Why does a specific utility work intermittently or not at all? Intermittent functionality almost always indicates missing or unstable privacy permissions. Check that vorssaint-utils has been granted **Accessibility**, **Screen Recording**, and **System Audio Recording** permissions in System Settings. If the permission state appears stuck, reset it entirely using `tccutil reset All com.vorssaint.utils` and re-grant access. ### How do I completely remove vorssaint-utils and reset all permissions? Run the comprehensive uninstall script located at [`Tools/uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/uninstall.sh), which removes the application, its launch agent, preference files, and resets all TCC permissions via `tccutil reset`. This ensures no cached permissions or settings persist that could interfere with future installations. ### What should I do if the App Switcher freezes or misses windows? Ensure you are running version 3.3.5 or later, which includes a refactor of the window querying logic in [`Sources/Vorssaint/App/AppDelegate.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/App/AppDelegate.swift) to cache results and skip hidden helper windows. If issues persist, check Accessibility permissions and run `./build/Vorssaint --selftest` to verify the window enumeration health.