# Troubleshooting (/docs/guides/troubleshooting)

Diagnose build, display, permissions, game assets and configuration failures.

For a reproducible log and system details, follow [Collect diagnostics](/docs/guides/diagnostics).

## The overlay does not start [#the-overlay-does-not-start]

Check the first error in the log, then verify that the copied `assets/` directory and `offsets.json` are beside the executable. Rebuild from the repository root if the build directory is stale:

```bash
cmake -B build -S .
make -j"$(nproc)" -C build
```

If the process is running but no window appears under Wayland, try the X11 backend:

```bash
sudo ./build/chudcs2 --x11
```

## The game reader cannot attach [#the-game-reader-cannot-attach]

Start CS2 before launching live mode, then refresh offsets:

```bash
sudo ./build/chudcs2 --update-offsets
```

If CS2 is not running, the refresh keeps the existing `offsets.json` and reports that it could not resolve live values. Check that the file is readable from the executable directory.

## Input features do not work [#input-features-do-not-work]

Input modules require `/dev/uinput`. Confirm that the process has permission to open it and that the feature keybind is active. Focus checks can disable game activity while another window is focused. Test the overlay with the relevant focus setting disabled only on an isolated development session.

## The overlay is misaligned [#the-overlay-is-misaligned]

Check monitor selection, game width and height, scaling mode, custom offsets, and `menu_scale`. Under Hyprland, follow [Hyprland setup](/docs/guides/hyprland). Compare Wayland behavior with `--x11` to determine whether the issue is compositor-specific.

## Player models or map geometry are missing [#player-models-or-map-geometry-are-missing]

Check **VPK Path** in **Debug**. A custom path must name the `pak01_dir.vpk` file. Save and restart after changing it. See [Game assets and VPK paths](/docs/guides/game-assets) for Steam library discovery and recovery.

## The web radar does not connect [#the-web-radar-does-not-connect]

Enable the feature and start its server in **Radar**. Check the displayed server status and both port settings. For another device, bind to a network interface and use the host machine's address in the browser. See [Web radar](/docs/guides/web-radar).

## A config is rejected [#a-config-is-rejected]

Validate the file directly:

```bash
./build/chudcs2 --validate-config
```

Use `CHUDCS2_CONFIG` for a file override and `CHUDCS2_CONFIG_DIR` for a profile directory override. Keep profile names free of path separators and reserved stems such as `_settings` and `offsets`.

To validate a different file, pass its path after `--validate-config`.

If the overlay disappears when switching windows, check [Focus and shortcuts](/docs/guides/focus-and-shortcuts). For uneven updates or low FPS, see [Performance tuning](/docs/guides/performance).