Troubleshooting
Diagnose build, display, permissions, game assets and configuration failures.
For a reproducible log and system details, follow Collect diagnostics.
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:
If the process is running but no window appears under Wayland, try the X11 backend:
The game reader cannot attach
Start CS2 before launching live mode, then refresh 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 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
Check monitor selection, game width and height, scaling mode, custom offsets, and menu_scale. Under Hyprland, follow Hyprland setup. Compare Wayland behavior with --x11 to determine whether the issue is compositor-specific.
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 for Steam library discovery and recovery.
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.
A config is rejected
Validate the file directly:
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. For uneven updates or low FPS, see Performance tuning.
Was this page helpful?
Last updated on