Skip to content

Troubleshooting

shmitzas edited this page Nov 12, 2026 · 2 revisions

Troubleshooting

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.


Startup

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

Drawing

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

Navigation

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

Supported plugins

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

Native text

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

Panels

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

Translations

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

Clone this wiki locally