OBS WebSocket Connection Failed: Three Failures, Three Fixes

Short answer: An OBS WebSocket connection fails in one of three ways. Nothing answers on the port, so the server is off, the port is wrong or a firewall is in the way. Something answers but closes the connection right after you identify, which means the password is wrong. Or it connects but shows wrong scenes: a version or profile mismatch.

The error I leaked into the header

On 2 June 2026 I typed a wrong password into the OBS connection panel in streamerOS and read what came back. Not the friendly message. The raw, internal error object, printed straight into the status header at the top of the app, braces and field names included. Good enough for me, a terrible thing to show anyone else.

The streamerOS cockpit talks to OBS over WebSocket, so a failed connection is the first thing a new user can hit. That day I cleaned up two commits: one that made the connection errors readable, and one that stopped the header leaking raw error text. Then I did the testing I should have done first. I tried every way I could think of to make the connection fail, wrote down what each looked like, and kept the notes in my test log. This post is those notes, translated for someone who just wants OBS to connect.

If you have not set the server up yet, start with our OBS WebSocket setup guide. This post is for when it is set up and not working.

Failure one: auth is on and the password is wrong

On the test PC OBS was open with authentication enabled. I connected with a wrong password and then a blank one. OBS's remote protocol does not send back a polite "wrong password". Per my notes, it closes the socket during the identify step. The close code is 4009 in the protocol, and my code comment records that a close while waiting for the identify reply is therefore an authentication failure, not a random drop.

From the outside, that looks like a connection that opened and then died immediately. That is the signature to remember: connects, then closes at once means password. The message I show now says, in plain words, to check the password and make sure WebSocket is enabled.

The fix: in OBS, open the settings dialog under Tools. OBS's own remote control guide words the menu as "obs-websocket Settings" and tells you to enable authentication and set your own password; our setup guide uses the label "WebSocket Server Settings". Either way, it is the WebSocket server dialog in the Tools menu. Use Show Connect Info, copy the password and paste it. Retyping it by hand is how you get a trailing space.

With the correct password, the same test went through: handshake accepted, one scene found.

Failure two: nothing answers on the port

For this test I turned the WebSocket server off in OBS and did a full restart of the tool. The result was the quietest failure of the three. No error from OBS, because OBS was not listening. From the tool's side, the connection attempt simply fails.

Because this is what you see on a PC where OBS is closed, I made streamerOS stay silent about it at start-up: no error banner, no console noise, just a clean "no OBS connection" state and a manual connect button. That is a product decision. For you, the lesson is the opposite: silence from a tool is not proof that everything is fine. No answer at all means the server is not reachable.

Check these, in order:

1. Is OBS running? Obvious, and the answer is no more often than anyone admits.
2. Is the server enabled? The tick box in the same Tools dialog.
3. Is the port right? The v5 default in the version I test against is 4455. The old standalone plugin used 4444.
4. Is Windows blocking it? The first time OBS opens a port, a firewall dialog appears. If it was dismissed, check Windows Defender Firewall's allowed apps list.
5. Is the host right? localhost for a tool on the same PC; the streaming PC's LAN address for another machine.