> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lynxhub.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Resolve common issues, rendering problems, and system errors in LynxHub.

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](https://git-scm.com/downloads) 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+](https://github.com/PowerShell/PowerShell/releases/latest).

## 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.

<Warning>
  Performing a settings reset wipes all custom settings, saved quick commands, hotkeys, and history. It does not delete your downloaded modules or extensions.
</Warning>

## GitHub issues

If you cannot resolve your issue, report it on the GitHub repository:

1. Open the [GitHub Issues](https://github.com/KindaBrazy/LynxHub/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](https://discord.gg/e8rBzhtcnK).