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

# Troubleshooting

> Solutions to common OpenTrack issues and error messages

This guide covers common issues you might encounter when using OpenTrack and how to resolve them.

## Quick Diagnostics

Before diving into specific issues, try these general troubleshooting steps:

<Steps>
  <Step title="Check OpenTrack Version">
    Ensure you're running the latest version from the [releases page](https://github.com/opentrack/opentrack/releases).
  </Step>

  <Step title="Review Error Messages">
    Check the OpenTrack console/log for error messages. On Windows, run OpenTrack from Command Prompt to see console output.
  </Step>

  <Step title="Test with Default Profile">
    Create a new profile with default settings to rule out configuration issues.
  </Step>

  <Step title="Verify Hardware">
    Test your camera or tracking device with other applications to ensure it's working properly.
  </Step>
</Steps>

## Tracking Issues

<AccordionGroup>
  <Accordion title="Camera Not Detected">
    **Symptoms:** OpenTrack doesn't show your webcam in the camera list.

    **Solutions:**

    <Steps>
      <Step title="Check Camera Permissions">
        **Windows 10/11:**

        * Go to Settings → Privacy → Camera
        * Enable "Allow apps to access your camera"
        * Enable "Allow desktop apps to access your camera"

        **Linux:**

        ```bash theme={null}
        # Check if camera device exists
        ls -l /dev/video*

        # Add user to video group
        sudo usermod -a -G video $USER

        # Log out and back in for changes to take effect
        ```
      </Step>

      <Step title="Verify Camera Driver">
        **Windows:**

        * Open Device Manager
        * Look under "Cameras" or "Imaging devices"
        * If you see a yellow warning icon, update or reinstall the driver

        **Linux:**

        ```bash theme={null}
        # Install video4linux utilities
        sudo apt-get install v4l-utils

        # List available cameras
        v4l2-ctl --list-devices
        ```
      </Step>

      <Step title="Test Camera in Other Apps">
        Try opening the camera in:

        * Windows Camera app
        * Browser (webcam test websites)
        * Skype/Zoom

        If the camera doesn't work elsewhere, the issue is with the camera/driver, not OpenTrack.
      </Step>

      <Step title="Disconnect Other Applications">
        Close any applications that might be using the camera:

        * Video conferencing apps (Zoom, Teams, Skype)
        * Streaming software (OBS)
        * Browser tabs with camera access
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Poor Tracking Quality">
    **Symptoms:** Jittery tracking, loss of tracking, or incorrect head position.

    **Solutions:**

    <Tabs>
      <Tab title="Lighting">
        **Point Tracker (LED):**

        * Use bright, focused LED lights
        * Avoid ambient lighting in the background
        * Position lights to minimize reflections
        * Use at least 3 points for best results

        **ArUco Marker:**

        * Ensure even, bright lighting on the marker
        * Avoid shadows on the marker
        * Print marker at sufficient size (5cm+ recommended)

        **NeuralNet Tracker:**

        * Good room lighting helps face detection
        * Avoid strong backlighting
      </Tab>

      <Tab title="Camera Settings">
        Optimize camera settings:

        * **Resolution:** 640x480 is usually sufficient
        * **Frame Rate:** 30 FPS minimum, 60 FPS preferred
        * **Exposure:** Manual exposure prevents brightness changes
        * **Auto White Balance:** Disable for consistent colors
        * **Auto Focus:** Disable and set focus manually

        Access camera settings in:

        * OpenTrack → Options → Camera Settings
      </Tab>

      <Tab title="Filter Settings">
        Adjust filtering to improve stability:

        **For jittery tracking:**

        * Enable a smoothing filter (Accela, EMA)
        * Increase filter strength

        **For lag:**

        * Reduce filter strength
        * Use a faster filter (Accela instead of EMA)

        **For overshoot:**

        * Adjust mapping curves
        * Reduce response sensitivity
      </Tab>

      <Tab title="Position">
        **Camera placement:**

        * Mount camera at eye level
        * Distance: 50-80cm for most trackers
        * Ensure camera points directly at you

        **LED/Marker placement:**

        * Wide triangular pattern for stability
        * Avoid symmetrical patterns
        * Keep markers visible at all head angles
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Tracking Drift">
    **Symptoms:** Head position slowly drifts over time even when stationary.

    **Solutions:**

    1. **Re-center regularly:**
       * Bind a key to "Center" function
       * Press when looking straight ahead
    2. **Disable auto-center:**
       * Options → Output → Disable translation drift reduction
    3. **Check for heat issues:**
       * Some trackers (especially webcam-based) drift when warming up
       * Let camera warm up for 5 minutes before gaming
    4. **Update tracker firmware:**
       * For hardware trackers (TrackIR, etc.)
       * Check manufacturer's website
  </Accordion>

  <Accordion title="High CPU Usage">
    **Symptoms:** OpenTrack uses excessive CPU resources.

    **Solutions:**

    1. **Reduce camera resolution:**
       ```
       Options → Camera → Resolution → 640x480
       ```

    2. **Lower frame rate:**
       ```
       Options → Camera → FPS → 30
       ```

    3. **Disable preview window:**
       ```
       Hide the camera preview when not needed
       ```

    4. **Close unnecessary applications:**
       * Free up CPU for gaming
       * Disable background programs

    5. **Update OpenCV:**
       * Newer versions have better performance
       * Rebuild OpenTrack with latest OpenCV
  </Accordion>
</AccordionGroup>

## Game Integration Issues

<AccordionGroup>
  <Accordion title="Game Not Detecting OpenTrack">
    **Symptoms:** Game doesn't respond to head tracking.

    **Solutions by Protocol:**

    <Tabs>
      <Tab title="FreeTrack">
        **Windows:**

        1. **Install FreeTrack driver:**
           * Download from FreeTrack website
           * Install before launching game

        2. **Select FreeTrack in OpenTrack:**
           ```
           Output → freetrack 2.0 Enhanced
           ```

        3. **Enable TrackIR in game:**
           * Check game options for head tracking
           * Enable "TrackIR" or "Head Tracking"

        4. **Run as administrator:**
           * Right-click game executable
           * "Run as administrator"
      </Tab>

      <Tab title="UDP">
        **Network output:**

        1. **Check firewall:**
           ```powershell theme={null}
           # Windows Firewall - allow UDP port
           New-NetFirewallRule -DisplayName "OpenTrack UDP" `
             -Direction Outbound -LocalPort 5550 -Protocol UDP `
             -Action Allow
           ```

        2. **Verify IP address:**
           * For local: 127.0.0.1
           * For remote: Target computer's IP

        3. **Test with receiver:**
           ```bash theme={null}
           # Listen on UDP port
           nc -ul 5550
           ```
      </Tab>

      <Tab title="SimConnect">
        **Microsoft Flight Simulator:**

        1. **Install SimConnect SDK:**
           * Included with MSFS
           * Check installation
        2. **Run MSFS first:**
           * Start the game
           * Wait for main menu
           * Then start OpenTrack
        3. **Check SimConnect version:**
           * OpenTrack requires specific version
           * Update if necessary
      </Tab>

      <Tab title="X-Plane">
        **X-Plane plugin:**

        1. **Install Wine (Linux):**
           ```bash theme={null}
           sudo apt-get install wine
           ```

        2. **Configure output:**
           ```
           Output → Wine → X-Plane plugin
           ```

        3. **Copy plugin files:**
           * Follow X-Plane plugin installation guide
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Inverted or Reversed Axes">
    **Symptoms:** Looking left moves camera right, etc.

    **Solutions:**

    1. **Invert axes in mapping:**
       ```
       Mapping → Select axis → Enable "Invert"
       ```

    2. **Check game settings:**
       * Some games have invert options
       * Check for "Invert Head Tracking"

    3. **Verify tracker orientation:**
       * Some trackers have orientation settings
       * Check tracker-specific configuration
  </Accordion>

  <Accordion title="Tracking Range Too Large/Small">
    **Symptoms:** Small head movements cause excessive camera movement, or you need to move your head too much.

    **Solutions:**

    1. **Adjust mapping curves:**

       ```
       Mapping → Select axis → Adjust curve
       ```

       * **Too sensitive:** Reduce output maximum
       * **Not sensitive enough:** Increase output maximum
       * **Non-linear response:** Adjust curve points
    2. **Use presets:**
       * Try built-in curve presets
       * Import community profiles
    3. **Per-game profiles:**
       * Create separate profiles for different games
       * Save with descriptive names
  </Accordion>
</AccordionGroup>

## Build and Compilation Errors

<AccordionGroup>
  <Accordion title="CMake Configuration Fails">
    **Error:** `CMake Error: Could not find Qt5`

    **Solutions:**

    ```bash theme={null}
    # Specify Qt5 path
    cmake .. -DCMAKE_PREFIX_PATH=/path/to/qt5

    # Or use Qt5_DIR
    cmake .. -DQt5_DIR=/path/to/qt5/lib/cmake/Qt5
    ```

    **Error:** `CMake minimum version 3.13 required`

    **Solutions:**

    Update CMake:

    ```bash theme={null}
    # Linux
    sudo apt-get install cmake

    # Or download from cmake.org
    wget https://github.com/Kitware/CMake/releases/download/v3.26.0/cmake-3.26.0-linux-x86_64.sh
    ```
  </Accordion>

  <Accordion title="Missing Dependencies">
    **Error:** `opencv/cv.h: No such file or directory`

    **Solutions:**

    Install OpenCV:

    ```bash theme={null}
    # Debian/Ubuntu
    sudo apt-get install libopencv-dev

    # Fedora
    sudo dnf install opencv-devel

    # Windows
    # Download from opencv.org and set OpenCV_DIR
    ```

    **Error:** `Eigen3/Core: No such file or directory`

    **Solutions:**

    ```bash theme={null}
    # Debian/Ubuntu
    sudo apt-get install libeigen3-dev

    # Fedora  
    sudo dnf install eigen3-devel
    ```
  </Accordion>

  <Accordion title="Linker Errors">
    **Error:** `undefined reference to vtable`

    **Solutions:**

    1. **Link against opentrack-api:**
       ```cmake theme={null}
       target_link_libraries(opentrack-tracker-myplugin 
         PRIVATE opentrack-api)
       ```

    2. **Run moc on Q\_OBJECT classes:**
       * CMake should handle this automatically
       * Ensure .h files are in source list

    **Error:** `undefined reference to 'm'`

    **Solutions:**

    On Linux, ensure math library is linked:

    ```cmake theme={null}
    if(UNIX)
        target_link_libraries(${target} PRIVATE m)
    endif()
    ```
  </Accordion>
</AccordionGroup>

## Runtime Errors

<AccordionGroup>
  <Accordion title="Missing DLL Errors (Windows)">
    **Error:** `The code execution cannot proceed because <dll> was not found`

    **Common missing DLLs:**

    * `Qt5Core.dll`, `Qt5Gui.dll`, `Qt5Widgets.dll`
    * `opencv_world*.dll`
    * `MSVCP140.dll`, `VCRUNTIME140.dll`

    **Solutions:**

    1. **Install Visual C++ Redistributable:**
       * [Download VC++ 2015-2022 x64](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist)

    2. **Add Qt to PATH:**
       ```batch theme={null}
       set PATH=C:\Qt\5.15.2\msvc2019_64\bin;%PATH%
       ```

    3. **Copy DLLs to opentrack directory:**
       ```batch theme={null}
       copy C:\Qt\5.15.2\msvc2019_64\bin\Qt*.dll C:\opentrack\
       ```
  </Accordion>

  <Accordion title="Crash on Startup">
    **Symptoms:** OpenTrack crashes immediately or shows no window.

    **Solutions:**

    1. **Delete settings:**
       ```batch theme={null}
       # Windows
       del /f /q %LOCALAPPDATA%\opentrack\settings\*

       # Linux
       rm -rf ~/.config/opentrack/
       ```

    2. **Check graphics drivers:**
       * Update GPU drivers
       * Try software rendering:
       ```batch theme={null}
       set QT_OPENGL=software
       opentrack.exe
       ```

    3. **Run from terminal to see errors:**
       ```bash theme={null}
       # Linux
       ./opentrack 2>&1 | tee opentrack.log

       # Windows
       opentrack.exe > opentrack.log 2>&1
       ```
  </Accordion>

  <Accordion title="Plugin Load Failures">
    **Error:** `Failed to load plugin: <name>`

    **Solutions:**

    1. **Verify plugin exists:**
       ```bash theme={null}
       # Linux
       ls /usr/lib/opentrack/opentrack-tracker-*.so

       # Windows
       dir "C:\Program Files\opentrack\opentrack-tracker-*.dll"
       ```

    2. **Check dependencies:**
       ```bash theme={null}
       # Linux - check plugin dependencies
       ldd /usr/lib/opentrack/opentrack-tracker-aruco.so
       ```

    3. **Reinstall OpenTrack:**
       * Download fresh installer
       * Uninstall completely first
       * Install to clean directory
  </Accordion>
</AccordionGroup>

## Performance Issues

<AccordionGroup>
  <Accordion title="Stuttering or Frame Drops in Games">
    **Solutions:**

    1. **Lower OpenTrack update rate:**
       * Options → Output → Update rate: 60 Hz
    2. **Reduce camera resolution:**
       * Options → Camera → 640x480
    3. **Disable camera preview:**
       * Close preview window during gaming
    4. **Use performance power plan:**
       * Windows: High Performance mode
       * Disable CPU throttling
    5. **Close background apps:**
       * Discord, Chrome, etc.
       * Check Task Manager for CPU usage
  </Accordion>

  <Accordion title="High Latency">
    **Symptoms:** Noticeable delay between head movement and game response.

    **Solutions:**

    1. **Reduce filtering:**
       * Mapping → Reduce smoothing
       * Use faster filters (Accela)
    2. **Check camera exposure:**
       * Auto exposure adds latency
       * Set manual exposure
    3. **Increase camera FPS:**
       * Options → Camera → 60 FPS
    4. **Use wired connection:**
       * For UDP protocols
       * Wireless adds latency
  </Accordion>
</AccordionGroup>

## Getting Help

If you're still experiencing issues:

<CardGroup cols={2}>
  <Card title="GitHub Issues" icon="github" href="https://github.com/opentrack/opentrack/issues">
    Search existing issues or create a new one
  </Card>

  <Card title="Community Wiki" icon="book" href="https://github.com/opentrack/opentrack/wiki">
    Check the wiki for tracker-specific guides
  </Card>

  <Card title="IL-2 Sturmovik Forums" icon="comments">
    Russian community forum with many experienced users
  </Card>

  <Card title="Reddit" icon="reddit">
    r/hotas and flight sim communities
  </Card>
</CardGroup>

### Information to Include

When asking for help, provide:

* OpenTrack version (Help → About)
* Operating system and version
* Tracker type being used
* Game and protocol
* Error messages (full text)
* Steps to reproduce the issue

<Note>
  OpenTrack developers are friendly and responsive. Don't hesitate to submit an issue or feature request!
</Note>