Troubleshooting

The quickest way to see what is going on is to turn on debug logging: the client logs every message that it sends and receives. The test app shows the same traffic, and what OBS Studio answers to a request you try by hand.

ConnectAsync returns false

It returns false when OBS Studio could not be reached, when it did not complete the handshake within 10 seconds, when it refused the password, or when Disconnect() was called in the meantime. Check, in this order:

1. OBS Studio is running, and its WebSocket server is enabled: Tools → WebSocket Server Settings → Enable WebSocket server.
2. The port is the one that is shown there (4455 unless you changed it), and the hostname is the machine that runs OBS Studio.
3. The password is the server password. With the wrong one, OBS Studio closes the connection with AuthenticationFailed.
4. Nothing else answers on that port: a service that accepts the connection but is not obs-websocket never completes the handshake.
5. A firewall on the machine that runs OBS Studio lets the port through, when you connect from another machine.

To see why a connection ended, look at the close code:

client.ConnectionClosed += (_, e) =>
    Console.WriteLine($"{e.WebSocketCloseCode}: {e.WebSocketCloseDescription}");

Close code	Meaning
NormalClosure	The connection was closed on purpose, for example by Disconnect().
EndpointUnavailable	OBS Studio is going away.
AuthenticationFailed	The password is wrong.
SessionInvalidated	The session was ended in OBS Studio (the Kick button of the session list). AutoReconnect is switched off: obs-websocket requires that a client does not reconnect automatically after this. (Up to and including 4.0.0-beta1 the client reconnected anyway.)
NotIdentified, MessageDecodeError, InvalidDataFieldValue, ...	OBS Studio refused a message of the client. This should not happen: please open an issue with the debug log.

A request throws TimeoutException

OBS Studio did not answer within RequestTimeout, which is 500 milliseconds by default.

• Some requests take OBS Studio longer, a screenshot of a large source for instance. Raise RequestTimeout.
• OBS Studio runs many requests on its interface thread: switching scenes, creating, renaming and removing scenes and inputs, changing the scene collection or the profile. That thread can be busy for seconds (while it loads a scene collection, or on a machine that has a lot to do): in a test on a development machine one scene switch waited for 9 seconds, while the requests that do not need the thread were answered all the time. Raise RequestTimeout if your application does these things on a busy machine. A request that timed out is not undone: OBS Studio may still carry it out when the thread is free again (the scene switch above was made about 4 seconds after the client had given up on it), so read the state again before you send the request again.
• A batch that sleeps needs a timeout that is longer than all its sleeps: pass timeOutInMilliseconds to SendRequestBatchAsync.
• Every request of your program times out after a PropertyChanged or statistics handler waited for one. Those handlers run on the thread that causes the change, which can be the one that reads the responses, and a handler that waits there (.Result, .Wait()) keeps it from reading. Do not wait for a response in them. The handlers of the events of OBS Studio run on a thread of their own, and one that waits there only delays the events behind it (up to and including 4.0.0-beta1 they ran on the thread that reads, so such a handler made every request time out). See the rules for handlers.

A request throws ObsClientException: "Not connected."

The client is not in the Connected state: ConnectAsync was not called, it returned false, or the connection was lost. Watch ConnectionState and ConnectionClosed, and use AutoReconnect to have the client come back.

A request throws ObsResponseException

OBS Studio refused the request. ErrorCode says why and ErrorMessage is the comment of OBS Studio. The common ones:

ErrorCode	What it means
ResourceNotFound (600)	The scene, input, filter or other resource does not exist. A name has to match exactly, or use the UUID.
ResourceAlreadyExists (601)	You created something with a name that is taken.
InvalidResourceState (604)	The resource is in a state that does not allow the request.
OutputRunning (500), OutputNotRunning (501)	You started an output that already runs, or stopped one that does not.
StudioModeActive (505), StudioModeNotActive (506)	The request only works with Studio Mode off, or on.
MissingRequestField (300), InvalidRequestField (400), InvalidRequestFieldType (401), RequestFieldOutOfRange (402), RequestFieldEmpty (403)	An argument is missing or wrong.
UnknownRequestType (204)	The obs-websocket of your OBS Studio does not know the request: it is older than the request.
RequestProcessingFailed (702), ResourceActionFailed (701)	OBS Studio tried and failed. The comment tells what.
NotReady (207)	OBS Studio is not ready yet (for example just after it started). The client tries again by itself, see timeouts and retries.

To find out whether your OBS Studio supports a request, ask it:

VersionResponse version = await client.GetVersion();
bool canListCanvases = version.AvailableRequests.Contains("GetCanvasList");

An event does not arrive

• Is the event part of what you subscribed to? ConnectAsync subscribes to All, and All does not include the four high-volume events. See Choosing the events you receive.
• Is it a VendorEvent? That needs the Vendors subscription, which All includes, but a narrower choice does not.
• The Events page of the test app lists every event that OBS Studio sends, so you can see whether OBS Studio sends it at all.

A response is missing a member, or has a value you do not expect

The protocol only describes nested objects in prose, so the client may not know a member that your OBS Studio sends. The Comparison view of the test app lists what OBS Studio sent and the client does not return. If you find one, please open an issue.

Asking for help

Open an issue and tell us:

• the version of OBSClient, of OBS Studio and of obs-websocket (GetVersion() returns the last two),
• what you did, and what you expected to happen,
• the debug log of the messages around it. Remove your password and stream key before you share a log.