Repository navigation
Troubleshooting
shmitzas edited this page Nov 12, 2026
·
2 revisions
CustomHUD's console lines start with [CustomHUD]. Warnings and errors always print; DetailedLogging adds a line for every frame drawn, naming the menu id and layout and timing each step on the game thread.
| Problem | Cause | Solution |
|---|---|---|
| Every menu on the server fails to open |
menus.jsonc selects customhud.panorama, but CustomHUD did not load |
Fix CustomHUD's load error, or remove Renderer until it loads |
| Plugin does not load | SwiftlyS2 older than 1.5.0 | Update SwiftlyS2 |
No Renderer 'customhud.panorama' registered. line |
CustomHUD did not load | Check the server log for its load error |
| Config edits ignored | Edited the wrong copy | Config lives in addons/swiftlys2/configs/plugins/CustomHUD/
|
| A setting change did nothing |
RendererId needs a restart |
Restart |
config.jsonc still has … from an older CustomHUD, which this version does not read. |
The file was written by a CustomHUD before layout names | Delete config.jsonc and restart, then set again what you had changed — Configuration
|
NativeText captured HUD messages; it is now set per kind in Messages, … |
The old file captured messages | Set Center, Alert or Notify under Messages — Native Text Capture
|
config.jsonc: Menus.ShopCore.Keyboard "menu_locker_v2" is no keyboard layout for ShopCore, so it draws in "menu_list_v2". (or another setting) |
A name or value CustomHUD cannot use | Fix the setting it names — Layouts |
config.jsonc could not be read, so the settings it held before stay in use: … |
A value of the wrong type, such as text where a number goes | Fix the value the line names |
config.jsonc: DefaultNavMode and MaxVisibleLines apply only with "MenuConfig": "customhud"; … |
You changed them while MenuConfig is "swiftlys2"
|
Set "MenuConfig": "customhud", or set the values in menus.jsonc — Starting mode
|
Menus.InputMethod "…" in configs/menus/menus.jsonc is not buttons, chat, wasd, numbers or mouse |
A typo in Menus.InputMethod
|
Fix it. Until then players start in buttons mode |
| Problem | Cause | Solution |
|---|---|---|
| Menus still draw as centre-screen HTML |
menus.jsonc does not select CustomHUD |
Set "Renderer": "customhud.panorama" under "Menus" — Installation
|
| One plugin's menus still draw as centre-screen HTML | It uses the deprecated Core.MenusAPI, or its menu's own section in menus.jsonc names another renderer |
Remove that section's Renderer. A Core.MenusAPI plugin stays as it is until it moves to Core.Menu
|
Nothing on screen, though DetailedLogging shows applied slot=… menu=…
|
The player lacks the Workshop addon, or a layout of your own names a file the addon does not have | Serve the addon with AddonsManager, and point File at a shipped file
|
Render failed for <menu id>., and the menu does not draw |
A layout of your own has RowSlots outside 1–256, or another fault the error names |
Fix the layout |
| Rows missing from a page | A layout of your own has RowSlots above the rows its file has |
Lower it — Your own layouts |
| Text in the wrong places, or a layout half empty | A layout of your own names panels or variables its file does not declare | Use the names the file declares |
A row draws blank; log: … threw while rendering a row past core's window; drawn blank.
|
That plugin's component threw | Report it to the plugin |
| Problem | Cause | Solution |
|---|---|---|
!setnav and !hudscale choices are forgotten after a restart |
Cookies is not installed; the log says Cookies was not found; player preferences are in-memory only.
|
Install Cookies |
Choices forgotten with Cookies installed; log: Cookies is loaded but its contract assembly is unavailable; restart the server.
|
Cookies was added while the server ran | Restart the server |
| Choices last only until the player reconnects | The player has no SteamID, as on a LAN server | Expected |
| Number keys do nothing | The player is not in numbers mode, or the keys are unbound |
!setnav numbers, then bind the keys — Commands
|
| Tab does not close the menu, or E does not select |
mouse and numbers modes ignore the keys menus.jsonc binds — Modes
|
Click × or <, or press 9; select by clicking or by number |
| A menu cannot be closed | Its plugin removed the close key, as MixScrims' picks do | Expected |
| No menu sounds | Mouse and numbers input plays none | Expected |
| W and S walk the player while a menu is open |
wasd mode does not freeze movement |
Expected |
| A page holds fewer rows than expected |
MaxVisibleLines (default 5), the menu's own page size, or six in numbers mode |
Raise MaxVisibleLines where MenuConfig reads it — Pages
|
Tab reached the menu router for player … although CustomHUD removed it this tick, so core acted on it. (or another key) |
SwiftlyS2 acted on a key CustomHUD hides from it in mouse, numbers or wasd mode — Modes
|
Report it with your SwiftlyS2 version |
| Problem | Cause | Solution |
|---|---|---|
A supported plugin's menus draw as the list; log: <Plugin> is loaded, but CustomHUD cannot read its API (…), so its menus draw plain.
|
The plugin is older than it needs to be | Update it |
'WeaponSkins.API' is published, but not as the WeaponSkins contract CustomHUD reads, so those menus draw plain. |
Another plugin publishes that key with its own API | Expected |
Drawing a <Plugin> page failed; it draws as a plain menu. |
That plugin's API threw while CustomHUD read it | Report it with both versions |
A supported plugin is missing from the Drawing <Plugin>'s menus from its API. lines at start |
The plugin is not installed, or failed to load | Check its own startup errors |
| WeaponSkins has no weapon-category tabs or pins | WeaponSkins older than 0.9.0 | Update it |
Ranks' Custom rank icons show only a colour |
The icon numbers are outside 0–18 and 26283401–26283500
|
Expected — Ranks |
| The server hitches as VIP pages change | VIPCore older than 1.3.1 reads its whole config on every group and perk lookup | Update VIPCore. With DetailedLogging, each applied line's build= is the page's own time |
| Problem | Cause | Solution |
|---|---|---|
| Nothing is captured | Every kind under Messages is "game", or a name is misspelt, which the console logs |
Set the kind to "hud_text" or "hud_alert", then check it with !ch_test center or !ch_test alert — Native Text Capture
|
| Chat lines vanish from chat |
Messages captures Chat or ChatEndOfRound
|
Set it to "game"
|
| Centre-screen HTML is not captured |
SendCenterHTML is not a text message |
Expected |
Native text capture threw; passing the message through. |
A capture fault; the game showed the message instead | Report it |
| Problem | Cause | Solution |
|---|---|---|
| A plugin's panel never appears | The player is a bot or not yet authorised by Steam, or lacks the Workshop addon | Expected for bots; serve the addon to everyone |
Show returns false
|
The panel name is neither a shipped panel nor in PanelLayouts, or its File is empty |
Fix it — Your own layouts |
| Problem | Cause | Solution |
|---|---|---|
| Lithuanian never shows | CS2 has no Lithuanian client language | Set SwiftlyS2's Language to lt and UsePlayerLanguage to false — Translations
|
| A translation edit did nothing | Translations load at start | Restart |
| Your translation edits are gone | An update replaced resources/translations/
|
Copy them back |
| A hint shows stray characters | A colour tag in a customhud.hint line |
Remove it: hints are plain text |