What causes "Wrong video options specified" in hcengineering/platform?

Ensure the client sends heartbeats/keepalives more frequently than perClientAliveTimeoutSeconds.

hcengineering/platform · warning · Error

Wrong video options specified

Error message

Wrong video options specified

What it means

BackRPC server's checkAlive loop in foundations/net/packages/backrpc/src/server.ts detects that a registered client has not been seen for longer than its perClientAliveTimeoutSeconds and logs this warning before tearing the connection down via handleClose(..., true). The client is marked dead and its mappings are cleaned up; any pending calls to it will fail.

Source

Thrown at desktop/src/ui/screenShare.ts:125

            reject(new Error('No source selected'))
          }
        },
        (val) => {
          if (val != null) {
            wasSelected = true
            if (options === undefined) {
              options = {}
            }

            if (options.resolution === undefined) {
              options.resolution = ScreenSharePresets.h1080fps30.resolution
            }

            const constraints = screenCaptureToDisplayMediaStreamOptions(options)

            if (constraints.video === undefined) {
              log.error('Wrong video options specified')
              throw new Error('Wrong video options specified')
            }

            constraints.video = {
              mandatory: {
                ...(typeof constraints.video === 'boolean' ? {} : constraints.video),
                chromeMediaSource: 'desktop',
                chromeMediaSourceId: val
              }
            } as any

            void window.navigator.mediaDevices.getUserMedia(constraints).then((stream) => {
              const tracks = stream.getVideoTracks()
              if (tracks.length === 0) {
                log.error('No video track found')
                throw new TrackInvalidError('No video track found')
              }
              const screenVideo = new LocalVideoTrack(tracks[0], undefined, false, {
                loggerName: this.roomOptions.loggerName,

View on GitHub (pinned to 63e28dc964)

Solutions

Ensure the client sends heartbeats/keepalives more frequently than perClientAliveTimeoutSeconds.
Check client logs/process health — the client likely crashed, hung, or its machine went to sleep.
Tune timeouts: raise perClientAliveTimeoutSeconds server-side or lower the client heartbeat interval to leave headroom.
Implement automatic client reconnection with re-registration after being marked dead.

Example fix

// before
setInterval(() => sendHeartbeat(), 120_000) // 120s > server timeout of 60s
// after
setInterval(() => sendHeartbeat(), 15_000) // well under the 60s per-client timeout

Defensive patterns

Strategy: retry

Try / catch

client.on('closed', async (clientId) => {
  if (wasMarkedDeadByTimeout(clientId)) {
    await backoffReconnect() // reconnect and re-register with the BackRPC server
  }
})

Prevention

Send client heartbeats at an interval well below perClientAliveTimeoutSeconds (e.g. 1/4 of the timeout).
Implement automatic reconnection with exponential backoff and re-registration on the client.
Avoid long-blocking work on the client's event loop that can starve heartbeat sends.
Monitor and alert on 'marking as dead' warnings to detect flaky clients or networks early.

When it happens

Trigger: A client's lastSeen timestamp exceeds perClientAliveTimeoutSeconds * 1000 — i.e. no keepalive/heartbeat or any traffic from that client within its timeout window while the periodic check runs.

Common situations: Client process crashed or was killed without closing the socket; network partition, NAT/firewall dropping idle connections; client machine asleep or suspended; misconfigured keepalive interval longer than the server's per-client timeout.

Related errors

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/3ab3e26e848b5413. Report an issue: GitHub.