STREAMING GUIDE / CREATOR PROJECTS

OBS WebSocket not connecting: diagnose the failed layer

A timer, control panel, or playlist helper can fail before connecting to OBS—or connect successfully and still target the wrong source. These checks tell the difference.

START HERE

Check OBS's actual WebSocket port, keep authentication enabled, and match the client to the server's protocol. Test a harmless source change in an offline scene. A reachable port does not prove authentication succeeded, and a missing source is a different problem from a failed connection.

Start with one OBS instance and one client

Do this while you are not live. Save the current scene collection and stop extra copies of the automation you are troubleshooting. Write down the OBS version, client version, and whether they run on the same computer. Multiple OBS instances or duplicate helper processes make a correct configuration look inconsistent.

OBS includes WebSocket control from version 28 onward. On a current installation, first inspect its built-in settings rather than installing another server plugin. Old tutorials for protocol 4.x do not describe the current 5.x connection.

Match the server's actual connection details

  1. Open Tools → WebSocket Server Settings in the OBS instance you intend to control. Enable the server and leave authentication enabled.
  2. Read the configured port and use Show Connect Info to obtain its password. The usual 5.x port is 4455, but the value shown in your installation takes priority.
  3. For a helper on the same computer, use localhost. For a helper on another device, localhost means that other device; use the OBS computer's reachable LAN address instead.
  4. Enter the password exactly in the client. If the client has separate host and port fields, do not paste a whole WebSocket URL into the host field unless its documentation requests one.
  5. Save the client configuration, restart that helper, and read its first connection result.

Changing the OBS password requires updating every authorized controller that uses it. Do not turn authentication off to conceal a mismatch.

Use the error to choose the next check

ObservationNext check
Connection refusedConfirm OBS is open, the server is enabled, and the selected computer and port are correct.
Connection times outCheck that the destination is reachable. For a LAN client, inspect the specific OBS/firewall rule and network isolation.
Authentication failsRecopy the current server password and check the client has saved the change.
Connected, then an unsupported request or protocol errorCheck whether the client supports WebSocket 5.x. A legacy 4.x client cannot be repaired merely by changing its port.
Connected, but a source or scene cannot be foundCompare exact names in the active scene collection and the helper's configuration.

In Windows PowerShell, Test-NetConnection localhost -Port 4455 is an optional reachability check; substitute the port actually configured. A successful TCP result establishes only that a service answered. It does not validate the OBS password, protocol handshake, or requested source.

Check the settings used by this site's helpers

Subathon Timer and YouTube Player use OBS_HOST, OBS_PORT, and OBS_WEBSOCKET_PASSWORD in their respective config.py files. Edit the configuration beside the copy you actually launch, then restart it. A second extracted folder is a common reason changes appear ineffective.

For Subathon Timer, a valid connection also needs a matching text source in the selected scene. Continue with the timer display checklist after basic access works. YouTube Player can be isolated with ENABLE_OBS = False; if Chrome then works, troubleshoot its OBS connection separately.

Prove recovery before enabling automation

Use a disposable scene or text source. Make one harmless change with the controller, confirm only the intended OBS instance changes, and restore the scene. Restart the helper once to check that its saved settings survive. If the tool can start or stop streams, leave those actions disabled until this small test passes.

A same-computer setup does not need router port forwarding. For a remote controller, grant only the access its documented connection requires; exposing an OBS control port publicly is not a troubleshooting step. When reporting a failure, include the versions, same-PC/LAN distinction, exact error, and attempted action. Remove passwords and connection URLs before sharing screenshots or logs.

Sources & version notes

Documentation checked November 18, 2026. Use the platform and version notes in this guide when comparing settings. The troubleshooting checks are intended for your own setup; this review date does not represent hardware testing.