Skip to content

Troubleshooting

Randy Northrup edited this page Nov 12, 2026 · 3 revisions

Troubleshooting

Starting up

Problem What to check
A message says CrossChat can't reach OBS's WebSocket server In OBS: Tools → WebSocket Server Settings, tick Enable WebSocket server. CrossChat connects by itself once it's on
OBS refused CrossChat's WebSocket password Leave password empty in config.json so CrossChat reads it from OBS
CrossChat keeps stopping Press Start the hub again in Tools → Scripts, then look in the log below
"Windows protected your PC" Choose More info, check the publisher says Randy Northrup, then Run anyway

Widgets

Problem What to check
Widgets show nothing Is CrossChat running? With OBS: is crosschat.lua loaded? Press Start the hub again in Tools → Scripts. Use the http://127.0.0.1:4466/... address, not a local file
The theme didn't change on stream Save it in the Studio, and check the source's address names the right ?theme=
Old look after an update Right-click the source → Refresh cache of current page
A shared theme looks different It may use a Google Font that needs internet, or a font you don't have
On Linux, no Browser Source in OBS Ubuntu's and Debian's own OBS package leaves it out. Use OBS from Flathub or the OBS Project's PPA

The chat window and replies

Problem What to check
"Replies to YouTube, X, TikTok, Facebook, Instagram and Rumble go out through the CrossChat window in Chrome or Edge with the extension" Add the extension, then close the chat window and open it again
The window says the extension is out of date Loaded unpacked: open chrome://extensions (or edge://extensions) and press the reload arrow on CrossChat. From the Chrome Web Store: switch on Developer mode there and press Update
A reply to one platform failed The chat window says why: not signed in, message too long, or chat not open. YouTube replies need you signed in to YouTube in the same browser
The dock in OBS says "Couldn't load that page!" OBS opened it before CrossChat was ready. Press Click here to retry in the dock
"This CrossChat has no Twitch app Client ID" This build can't connect to Twitch's API, so Twitch chat is read only in it

Platforms

Problem What to check
X stopped at a step The X page's banner and the chat window name the step. Finish by hand. If it keeps happening, X may have changed its page, so open an issue
YouTube chat doesn't appear on an unlisted live CrossChat finds your live on your channel's public live page, which doesn't list unlisted lives
TikTok, Facebook or Instagram went quiet CrossChat reads their own pages, so a redesign can break it until CrossChat is updated. Open an issue
Rumble replies don't go out Keep Rumble's chat window open while you're live, and stay signed in to Rumble in the same browser

Read aloud

Problem What to check
Nothing is read aloud Is it on in Settings → Text to speech? Is the CrossChat window open in Chrome or Edge, not just docked in OBS?
"Click anywhere in this window once" Browsers only speak after a click
On Linux, no voices You need speech-dispatcher with a voice, and Google Chrome started with --enable-speech-dispatcher

For the phone companion, see its troubleshooting.

Where the logs are

  • CrossChat: crosschat.log in %LOCALAPPDATA%\CrossChat (on a Mac ~/Library/Application Support/CrossChat, on Linux ~/.local/share/CrossChat).
  • OBS: Help → Log Files, lines with crosschat.lua.

Still stuck? Open an issue with what you tried and the relevant log lines. Check the log first for anything private.

Clone this wiki locally