Skip to main content
If you run into issues while using LynxHub, use this guide to resolve common problems.

​
macOS security warning

LynxHub is currently an unsigned macOS application. To bypass the security warning on your first launch:
  1. Right-click (or Control-click) the application.
  2. Click Open from the menu.
  3. Click Open in the confirmation dialog.
You only need to perform this bypass once.

​
Prerequisites errors

Ensure you have installed the required system tools to prevent app issues:
  • Git missing: Repository operations, branch switching, and cloning will fail. Download and install Git and ensure it is in your system path.
  • PowerShell 7+ missing: Terminal processes may fail or behave unexpectedly on Windows. Download and install PowerShell 7+.

​
Startup loop or empty window

If the application fails to start, gets stuck on the loading window, or opens as a solid black or white screen, a corrupted or incompatible plugin is likely causing the crash. To resolve this issue:
  1. Navigate to the plugins folder for your operating system:
    • Windows: %USERPROFILE%\Documents\LynxHub\Plugins
    • macOS: ~/Documents/LynxHub/Plugins
    • Linux: ~/Documents/LynxHub/Plugins
  2. Delete all directories and files inside this folder to uninstall all plugins.
  3. Launch LynxHub again.
  4. If the application launches successfully, you can reinstall your plugins one by one to identify the faulty plugin.
  5. If the application still fails to start, submit a bug report on GitHub.

​
Rendering and graphics issues

If you experience user interface freezing, lagging, or black screens, disable hardware acceleration:
  1. Click Settings in the application sidebar.
  2. Click Performance to open the performance options.
  3. Disable the Use Hardware Acceleration toggle.
  4. Restart the application.

​
Terminal spawning failures

If the integrated terminal fails to spawn or crashes immediately on Windows:
  1. Click Settings in the application sidebar.
  2. Click Terminal to open the terminal options.
  3. Change the Use Conpty (Windows) setting to No.
  4. Restart the application.

​
Factory reset

If you experience persistent errors, you can reset your settings to defaults:
  1. Click Settings in the application sidebar.
  2. Click Data Management to open the data settings.
  3. Scroll down to the Clear section.
  4. Click Reset Settings (Restart Required).
  5. Click Reset & Restart in the confirmation dialog.
Performing a settings reset wipes all custom settings, saved quick commands, hotkeys, and history. It does not delete your downloaded modules or extensions.

​
GitHub issues

If you cannot resolve your issue, report it on the GitHub repository:
  1. Open the GitHub Issues page.
  2. Search the existing issues to see if your problem has already been reported.
  3. If the issue is new, click New Issue.
  4. Select the bug report template.
  5. Complete the template by specifying:
    • Your operating system.
    • The LynxHub version.
    • Step-by-step instructions to reproduce the behavior.
    • Log files: Attach the log files (main.log) to help debug the issue. You can find the log directory at:
      • Windows: %USERPROFILE%\AppData\Roaming\LynxHub\logs
      • macOS: ~/Library/Logs/LynxHub
      • Linux: ~/.config/LynxHub/logs
    • Any screenshots or log outputs.
  6. Click Submit New Issue.

​
Discord support

You can get real-time assistance and connect with the community on the LynxHub Discord.
Last modified on June 18, 2026