Skip to main content
Solutions to common problems with the Battles Overlay.

​
Blank Overlay in OBS

The Browser Source shows a blank or white screen.
  1. Check your API key - Make sure the key is valid and has not been revoked. Test it by pasting it into the editor.
  2. Verify the URL - Confirm you copied the full overlay URL from the editor.
  3. Set custom CSS - In the OBS Browser Source properties, add the following custom CSS:
body {
	background: transparent;
}
  1. Check OBS version - Browser Source requires a Chromium-based renderer. Make sure OBS Studio is up to date.

​
Widgets Not Showing

Specific widgets are missing from the overlay.
  1. Check widget is enabled - Open the editor and verify the widget toggle is on.
  2. Check API permissions - Your API key may be missing the required scope. Grayed-out widgets in the editor indicate missing permissions. See API Permissions.
  3. Check context selection - Team Stats and Organization Stats require a team or organization to be selected in the editor.

​
Stale or Outdated Data

Stats on the overlay are not updating.
  1. Check refresh interval - The default is 60 seconds. You can lower it in the editor’s advanced settings for faster updates.
  2. Verify internet connection - The overlay requires an active connection to fetch data from the API.
  3. Refresh the Browser Source - Right-click the Browser Source in OBS and select Refresh cache of current page.

​
Overlay Not Transparent

The overlay has a solid background instead of being see-through. In the OBS Browser Source properties, add this custom CSS: 
body {
	background: transparent;
}
Also make sure the Opacity setting in the editor is not set to 100%. An opacity of 70-85% typically works well for stream overlays.

​
Overlay Too Small or Too Large

Widgets appear at the wrong size on stream.
  1. Adjust scale in the editor - Use the scale slider in the sidebar style controls to resize all widgets proportionally.
  2. Check OBS dimensions - Set the Browser Source width to 1920 and height to 1080 for the intended layout. Other resolutions may cause scaling issues.
  3. Use OBS transform - Right-click the source in OBS and use Transform > Edit Transform to fine-tune size and position.

​
”Invalid API Key” Error

The editor or overlay reports the API key is invalid.
  1. Check you replaced the key prefix - The URL copied from the editor contains only a key prefix (e.g., tb_a1b2c3d4...). You must replace it with your full API key. See Using Your API Key in the URL.
  2. Key may have been revoked - Go to Settings > Developer and check if the key still exists.
  3. Create a new key - If the key was deleted or revoked, create a new one with the Battles Overlay preset.
  4. Copy carefully - Make sure the full key is in the URL with no extra spaces or missing characters. The key format is tb_ followed by 64 hex characters.

​
Active Match Widget Not Showing

The Active Match widget is enabled but nothing appears.
The Active Match widget auto-hides when you have no active match. This is expected behavior - it will reappear automatically when a match starts.
If you have an active match and it still does not show:
  1. Check permissions - Ensure your API key has the matches.user_matches: read scope.
  2. Wait for refresh - The widget updates on the configured refresh interval. Wait up to 60 seconds (or your configured interval) for it to detect the match.
  3. Verify match status - The match must be in an active state (not completed or cancelled).

​
Lost API Key

You cannot retrieve a full API key after closing the creation dialog.
  1. Go to Settings > Developer
  2. Delete the old API key
  3. Create a new key with the Battles Overlay preset
  4. Save the new key immediately in a password manager or private note
  5. Update the API key in your overlay configuration in the editor
  6. Copy the overlay URL again and replace the key prefix with your new full key
  7. Update the URL in your OBS browser source
To avoid this in the future, always save your API key to a secure location the moment you create it.

​
Cannot Connect to OBS WebSocket

The dock cannot connect to OBS via WebSocket.

​
WebSocket Server Not Enabled

OBS does not enable the WebSocket server by default.
  1. In OBS Studio, go to Tools > WebSocket Server Settings
  2. Check Enable WebSocket Server
  3. Click Apply
  4. Try connecting again in the dock

​
Wrong Port

The default WebSocket port is 4455, but it can be changed in OBS.
  1. In OBS, go to Tools > WebSocket Server Settings
  2. Click Show Connect Info to see the current port
  3. Enter the correct port in the dock’s port field before connecting

​
Password Required

If OBS WebSocket has authentication enabled, you need the password.
  1. In OBS, go to Tools > WebSocket Server Settings
  2. Click Show Connect Info to reveal the password
  3. The dock will prompt you for the password when it detects authentication is required

​
Firewall Blocking the Connection

In rare cases, a firewall may block the local WebSocket connection.
  1. Ensure no firewall or antivirus software is blocking connections to 127.0.0.1 on the configured port (default 4455)
  2. Try temporarily disabling your firewall to test if that resolves the issue
  3. If it does, add an exception for OBS Studio or the specific port

​
Getting Help

If you cannot resolve your issue:
  1. Check the general troubleshooting guide
  2. Ask in the TeamBattles Discord
  3. Submit a support ticket