Publish: Diagnostics

This guide covers how to gather diagnostics for publishers and resolve common issues.

Getting statistics about a publisher's stream

The Vonage Video SDK exposes detailed stream-quality metrics through a high-level statistics API—recommended for most use cases—which provides audio, video, network, and sender-side statistics in a unified, session-aware form that remains stable across peer-connection transitions. For advanced debugging, the SDK also offers access to the raw WebRTC stats report, which reflects unprocessed peer-connection data.

Refer to the client observability developer guide for detailed information.

Test stream

You can publish a test stream and check its audio and video statistics to determine the type of stream (such as high-resolution or audio-only) supported by your connection.

To get statistics for a stream published by the local client, you must use a session that uses the Media Router (sessions with the media mode set to routed), and you must set the testNetwork property to true in the options object you pass into the Session.subscribe() method. You can then use the getStats() method of the Subscriber object to get audio and video statistics for the stream you publish.

Best practices when publishing

This section includes tips for successfully publishing streams.

Allowing Device Access

It is best practice to let your users know that they are going to be asked to allow access to their camera and microphone.

We find that by far the largest number of failures to publish are a result of users clicking the "deny" button or not clicking the allow button at all. We provide you with all of the events you need to be able to guide your users through this process:

publisher.on({
  accessDialogOpened: function (event) {
    // Show allow camera message
    pleaseAllowCamera.style.display = 'block';
  },
  accessDialogClosed: function (event) {
    // Hide allow camera message
    pleaseAllowCamera.style.display = 'none';
  }
});

It is also a good idea to serve your website over SSL. This is because Chrome only requires users to click to allow access to devices once per domain if that domain is served over SSL. This means that your users (if on Chrome) don't have to deal with that inconvenient allow/deny dialog box every time they load the page.

Split OT.initPublisher() and Session.publish()

Another thing we recommend is splitting the OT.initPublisher() and Session.publish() steps. This speeds up the initial connect time because you're connecting to the session while you're waiting for the user to click the allow button. So instead of:

session.connect(token, function (err) {
{... your error handling code ...}
if (!err) {
    var publisher = OT.initPublisher();
    session.publish(publisher);
  }
});

Move the OT.initPublisher() step to before you connect, as in the following:

var publisher = OT.initPublisher();
session.connect(token, function (err) {
{... your error handling code ...}
  if (!err) {
    session.publish(publisher);
  }
});

Resolution and frame rate

You can set the resolution and frame rate of the Publisher when you initialize it:

OT.initPublisher(divId, {
  resolution: '320x240',
  frameRate: 15
});

By default the resolution of a Publisher is 640x480, but you can set it to 1920x1080, 1280x720 or 320x240 as well. It is best to try to match the resolution to the size that the video will be displayed. If you are only displaying the video at 320x240 pixels then there is no point in streaming at 1280x720 or 1920x1080. Reducing the resolution can save bandwidth and reduce congestion and connection drops.

By default the frame rate of the video is 30 frames per second, but you can set it to 15, 7, or 1 as well. Reducing the frame rate can reduce the bandwidth required. Smaller resolution videos can have a lower frame rate without as much of a perceived difference to the user. So if you are using a low resolution, you might also want to think about using a low frame rate.

Troubleshooting

Follow the tips in this section to avoid connectivity issues when publishing. For general information on troubleshooting, see Debugging — Web.

Handling Errors

There are callback methods for both Session.publish() and OT.initPublisher(). We recommend handling the error responses to both of these methods. As mentioned earlier, it is best to split up these steps and call OT.initPublisher() before you have started connecting to your Session. It also makes error handling easier if you are not calling both of these methods at the same time. This is because both error handlers will fire if there is any error publishing. It is best to wait for OT.initPublisher() to complete and Session.connect() to complete and then call Session.publish(). This way you can handle all hardware related issues in the OT.initPublisher() callback and all network related issues in the Session.publish() callback.

var connected = false,
  publisherInitialized = false;

var publisher = OT.initPublisher(function(err) {
  if (err) {
    // handle error
  } else {
    publisherInitialized = true;
    publish();
  }
});

var publish = function() {
  if (connected && publisherInitialized) {
    session.publish(publisher);
  }
};

session.connect(token, function(err) {
  if (err) {
    // handle error
  } else {
    connected = true;
    publish();
  }
});

Access Denied

The highest number of failures to OT.initPublisher() are a result of the end-user denying access to the camera and microphone. This can either be handled by listening for the accessDenied event or by listening for an error response to the OT.initPublisher() method with a code property set to 1500 and a message property set to "Publisher Access Denied:". We recommend that you handle this case and surface a message to the user indicating that they should try to publish again and allow access to the camera.

publisher.on({
  'accessDenied': function() {
    showMessage('Please allow access to the Camera and Microphone and try publishing again.');
  }
});

Device Access

Another reason for OT.initPublisher() to fail is if OpenTok cannot get access to a camera or microphone. This can happen if there is no camera or microphone attached to the machine, if there is something wrong with the driver for the camera or microphone, or if some other application is using the camera or microphone (this only happens in Windows). You can try to minimize the occurrence of these issues by using our Hardware Setup Component or by calling the OT.getDevices() method directly. However you should also handle any error when calling OT.initPublisher() because something could still go wrong. For example, the user could have denied access to the camera or microphone. In this case, the error.name property is set to "OT_USER_MEDIA_ACCESS_DENIED":

publisher = OT.initPublisher('publisher', {}, function (err) {
  if (err) {
    if (err.name === 'OT_USER_MEDIA_ACCESS_DENIED') {
      // Access denied can also be handled by the accessDenied event
      showMessage('Please allow access to the Camera and Microphone and try publishing again.');
    } else {
      showMessage('Failed to get access to your camera or microphone. Please check that your webcam'
        + ' is connected and not being used by another application and try again.');
    }
    publisher.destroy();
    publisher = null;
  }
});

Network Errors

The other reasons for failures in publishing are usually due to some kind of network failure. We handle these in the callback to Session.publish(). If the user is not connected to the network, the callback function is passed an error object with the name property set to "OT_NOT_CONNECTED". If the user is on a really restrictive network connection that does not allow for WebRTC connections, the Publisher fails to connect, and the Publisher element will display a spinning wheel. This error has an name property set to "OT_CREATE_PEER_CONNECTION_FAILED". In this case recommend that you surface a message to the user indicating that they failed to publish and that they should check their network connection. Handling these errors looks like this:

session.publish(publisher, function(err) {
  if (err) {
    switch (err.name) {
      case "OT_NOT_CONNECTED":
        showMessage("Publishing your video failed. You are not connected to the internet.");
        break;
      case "OT_CREATE_PEER_CONNECTION_FAILED":
        showMessage("Publishing your video failed. This could be due to a restrictive firewall.");
        break;
      default:
        showMessage("An unknown error occurred while trying to publish your video. Please try again later.");
    }
    publisher.destroy();
    publisher = null;
  }
});

Losing Connectivity

Your Publisher can also lose its connection after it has already succeeded in connecting. More often than not, this will also result in the Session losing its connection, but that's not always the case. You can handle the Publisher disconnecting by listening for the streamDestroyed event with a reason property set to "networkDisconnected" like so:

publisher.on({
  streamDestroyed: function (event) {
    if (event.reason === 'networkDisconnected') {
      showMessage('Your publisher lost its connection. Please check your internet connection and try publishing again.');
    }
  }
});

Implementing Session Publish Retries

Transient publish failures are a known and recurring pattern in the Video API JS SDK, particularly on mobile browsers. When session.publish() fails, the SDK returns an error via its completion handler callback. The recommended approach is to implement application-level retry logic with a delay between attempts.

How session.publish() Works

session.publish() can be called in two ways:

• With a pre-initialized publisher: session.publish(publisher, callback) — you call OT.initPublisher() first, then pass the resulting publisher instance to session.publish(). This is the recommended approach as it separates media acquisition from stream creation, making error handling cleaner.
• Without a publisher instance: session.publish(targetElement, options, callback) — the SDK internally calls OT.initPublisher() for you. In this case, both media acquisition errors and stream creation errors surface through the single session.publish() callback.

// Recommended: split initialization from publishing
let publisherReady = false;
let sessionConnected = false;

const publisher = OT.initPublisher('publisher-container', publisherOptions, (err) => {
  if (err) {
    handleInitPublisherError(err); // hardware/media errors — see OT.initPublisher() errors below
    return;
  }
  publisherReady = true;
  maybePublish();
});

session.connect(token, (err) => {
  if (err) { /* handle connection error */ return; }
  sessionConnected = true;
  maybePublish();
});

function maybePublish() {
  if (sessionConnected && publisherReady) {
    publishWithRetry(session, publisher);
  }
}

Why Publish Failures Happen

The most common root causes for transient publish failures are:

• StreamCreateRequest timeouts (error 1500): The publisher failed to complete stream creation in a reasonable amount of time — typically caused by network delays during ICE/SDP negotiation.
• mediaStopped events during the publish flow, where media device access can be interrupted.
• Publisher object reuse without proper cleanup — reusing a publisher instance initialized with different constraints without calling unpublish and reinitializing.
• OT_NOT_CONNECTED — attempting to publish before the session is fully connected.
• OT_PERMISSION_DENIED — token does not have the publish role (non-retryable).

Errors from OT.initPublisher()

When you pre-initialize a publisher with OT.initPublisher(), all hardware and media acquisition errors are delivered to its completion handler — before session.publish() is ever called. Handle them in this callback using the per-error actions below: some require user action or a code fix, while transient media errors may be handled by reinitializing the publisher.

const publisher = OT.initPublisher('publisher-container', publisherOptions, (err) => {
  if (!err) {
    publisherReady = true;
    maybePublish();
    return;
  }

  // Hardware/media errors — handle before session.publish() is called
  switch (err.name) {
    case 'OT_REQUESTED_DEVICE_PERMISSION_DENIED':
      showMessage('Please allow access to your camera and microphone and try again.');
      break;
    case 'OT_HARDWARE_UNAVAILABLE':
    case 'OT_NO_DEVICES_FOUND':
      showMessage('Could not access your camera or microphone. Please check your devices.');
      break;
    case 'OT_SCREEN_SHARING_NOT_SUPPORTED':
    case 'OT_UNABLE_TO_CAPTURE_SCREEN':
    case 'OT_SCREEN_SHARING_EXTENSION_NOT_REGISTERED':
    case 'OT_SCREEN_SHARING_EXTENSION_NOT_INSTALLED':
      showMessage('Screen sharing is not available. Please check your browser settings.');
      break;
    default:
      showMessage('Could not initialize the publisher. Please try again.');
  }

  publisher.destroy();
});

Recoverable vs. Non-Recoverable Errors from session.publish()

Not all session.publish() errors are equal. Before implementing retry logic, it is essential to classify errors correctly — retrying on a non-recoverable error wastes time, degrades the user experience, and can mask real failures that require a different response.

Non-Recoverable Errors — Do Not Retry

These errors represent programmer mistakes, hard permission constraints, or invalid call context. Retrying will not resolve them. Instead, surface a meaningful message to the user or fix the application logic.

Recoverable Errors — Safe to Retry

These errors are typically caused by transient network conditions, signalling timeouts, or temporary platform unavailability. They are the primary target for retry logic.

Errors Requiring a Different Action (Not a Simple Retry)

Some errors are neither a simple retry nor a hard stop — they require a specific corrective action before retrying.

Putting It Together: Recommended Retry Pattern with Error Classification

async function publishWithRetry(session, publisher, attempt = 1) {
  const MAX_RETRIES = 3;
  const RETRY_DELAY_MS = 2000;

  const error = await new Promise((resolve) => {
    session.publish(publisher, resolve);
  });

  if (!error) {
    console.log('Publishing started successfully.');
    return;
  }

  // Non-recoverable: programmer error or hard permission constraint
  const nonRetryable = [
    'OT_NOT_CONNECTED',
    'OT_PERMISSION_DENIED',
    'OT_INVALID_PARAMETER',
    'OT_USER_MEDIA_ACCESS_DENIED',
    'OT_CHROME_MICROPHONE_ACQUISITION_ERROR',
    'OT_SCREEN_SHARING_NOT_SUPPORTED',
    'OT_SCREEN_SHARING_EXTENSION_NOT_REGISTERED',
    'OT_SCREEN_SHARING_EXTENSION_NOT_INSTALLED',
    'OT_CONSTRAINTS_NOT_SATISFIED',
    'OT_NO_VALID_CONSTRAINTS',
    'OT_NOT_SUPPORTED',
    'OT_STREAM_CREATE_FAILED',
    'OT_INVALID_AUDIO_OUTPUT_SOURCE',
    'OT_UNABLE_TO_CAPTURE_MEDIA',
  ];

  // Requires corrective action before retrying
  const requiresAction = [
    'OT_HARDWARE_UNAVAILABLE',
    'OT_NO_DEVICES_FOUND',
  ];

  if (nonRetryable.includes(error.name)) {
    console.error('Non-retryable error — user action or code fix required:', error.name);
    handleNonRecoverableError(error);
    return;
  }

  if (requiresAction.includes(error.name)) {
    console.warn('Device error — prompting user before retrying:', error.name);
    handleDeviceError(error);
    return;
  }

  // Recoverable: retry with backoff
  if (attempt < MAX_RETRIES) {
    console.warn(`Publish attempt ${attempt} failed (${error.name}), retrying...`);
    await delay(RETRY_DELAY_MS * attempt);
    await publishWithRetry(session, publisher, attempt + 1);
  } else {
    console.error('All publish attempts failed. Disconnecting user.');
    handlePublishFailure(session);
  }
}

function handleNonRecoverableError(error) {
  // Surface a meaningful message to the user based on error.name
  // e.g. for OT_USER_MEDIA_ACCESS_DENIED: "Please allow camera/mic access"
}

function handleDeviceError(error) {
  // Prompt the user to check their device, then allow them to retry manually
}

function handlePublishFailure(session) {
  session.disconnect();
}

Usage:

const publisher = OT.initPublisher('publisher-container', publisherOptions);

// Wait for session to be connected before publishing
session.connect(token, (err) => {
  if (err) { /* handle connection error */ return; }
  publishWithRetry(session, publisher);
});

Important: Publisher Cleanup Before Retrying

In most failure scenarios — including OT_TIMEOUT / OT_ICE_WORKFLOW_FAILED — the publisher instance can be reused directly for the next session.publish() call. You do not need to reinitialize it.

When a publish attempt fails, the SDK tears down the stream it was attempting to create and emits a streamDestroyed event on the publisher with reason: "reset". This is expected cleanup and does not require you to reinitialize the publisher — you can retry with the same instance. Note that "reset" is a general "the publisher's stream was torn down" reason (it is also emitted when you call publisher.destroy()), so treat it as a cleanup signal rather than a dedicated publish-failure indicator; use the error.name from the session.publish() callback to decide whether to retry.

The SDK does not automatically retry session.publish() on your behalf — retry logic must be implemented at the application level as shown above.

The only case where you must reinitialize the publisher with OT.initPublisher() before retrying is when the publisher's own destroyed event fires. This event is final and indicates the publisher object itself is no longer usable.

publisher.on('destroyed', () => {
  // Publisher object is no longer usable — reinitialize before retrying
  publisher = OT.initPublisher('publisher-container', publisherOptions);
});

// A streamDestroyed event with reason 'reset' is emitted by the SDK when it tears
// down the stream (during a failed publish attempt, or when you call publisher.destroy()).
// A 'reset' during a failed publish does NOT require reinitializing the publisher.
publisher.on('streamDestroyed', (event) => {
  if (event.reason === 'reset') {
    // Expected cleanup — reuse the same publisher instance
    return;
  }
  // Handle other streamDestroyed reasons as appropriate for your application
});

What NOT to Do

• Do not call OT.initPublisher() twice on the same publisher object with different constraints without cleaning up first (session.unpublish() → wait for streamDestroyed → then reinitialize).
• Do not retry on OT_PERMISSION_DENIED (user denied camera/mic access) — this requires user action, not a retry.
• Do not retry on OT_NOT_CONNECTED — ensure the session is connected before publishing.
• Do not retry indefinitely — cap at 3 retries and gracefully handle the failure.

Handling the mediaStopped Event

The media track can be stopped mid-publish. Listen for this event and treat it as a trigger to retry:

publisher.on('mediaStopped', async () => {
  console.warn('Media stopped during publish — retrying...');
  // Unpublish if already publishing, then retry
  try { session.unpublish(publisher); } catch (e) { /* ignore */ }
  await delay(2000);
  publishWithRetry(session, publisher);
});

Summary of Recommended Parameters

Handling Audio Capture Issues: audioAcquisitionProblem and audioAcquisitionProblemResolved

Beyond publish-level retries, there is a separate class of audio issues that can affect an active publisher: the client's audio device may fail to deliver audio data even after a successful publish. The Video API JS SDK exposes two events specifically for this scenario.

Common Causes

The audioAcquisitionProblem event is triggered when the SDK detects — via publisher stats — that the audio track has stopped delivering bytes to the peer connection, even though getUserMedia succeeded and the publisher appears active. The most common root causes are:

• Bluetooth audio device connected or disconnected mid-session: When a user plugs in or unplugs earphones, or connects Bluetooth headphones (e.g. AirPods) during an active session, the OS may switch the default audio device. The browser's audio pipeline can fail to re-acquire the microphone on the new device, resulting in zero audio bytes being sent.
• Audio device change at session start: Switching audio input very early in the session — within the first 1–2 seconds of publishing — is particularly prone to triggering the issue.
• Audio track ended by the browser or OS (trackEndedEvent): The browser can terminate the underlying audio track independently of any user action. The SDK detects this via a track.ended event and raises audioAcquisitionProblem with method: trackEndedEvent.
• Stats-based detection (no audio bytes flowing): After the peer connection reaches the connected state, the SDK polls publisher stats roughly every few seconds. If the audio track's outbound bytesSent does not increase between consecutive polls, audioAcquisitionProblem is raised (with method: getStats). When bytesSent starts increasing again, audioAcquisitionProblemResolved is raised.

The Events

These events are emitted on the publisher instance:

• audioAcquisitionProblem — fired when the SDK detects that the publisher has stopped sending audio (based on publisher stats), or when the underlying audio track fires an ended event. This does not necessarily mean the stream will fail, but it is an indicator that audio capture has been interrupted.
• audioAcquisitionProblemResolved — fired when audio transmission recovers after a previous audioAcquisitionProblem. If this event fires, no corrective action is needed.

Recommended Recovery Pattern

Start a short timer upon receiving audioAcquisitionProblem. If audioAcquisitionProblemResolved fires before the timer expires, audio has recovered on its own and no action is needed. If the timer expires without resolution, switch the audio source as a recovery action.

publisher.on('audioAcquisitionProblem', () => {
  // Start a 3-second timer
  const timeout = setTimeout(() => {
    // Problem not resolved — attempt recovery by switching audio source
    publisher.setAudioSource(newDeviceId);
  }, 3000);

  publisher.on('audioAcquisitionProblemResolved', () => {
    // Audio recovered — clear the timer, no action needed
    clearTimeout(timeout);
  });
});

Key Considerations

• Not a guaranteed failure indicator: audioAcquisitionProblem does not always lead to a subscription failure. Use it as an early signal to monitor and potentially act, not as a definitive failure event.
• Monitor publisher audio stats: After receiving audioAcquisitionProblem, you can also monitor the publisher's audio stats (e.g., via publisher.getStats()) to confirm whether audio transmission has truly stopped before taking action.
• Recovery action: Calling publisher.setAudioSource(newDeviceId) is the primary recovery mechanism. This switches the audio input device without requiring a full unpublish/republish cycle.
• Relationship to subscription timeouts: If audio is not recovered and the publisher continues sending no audio packets, subscribers may eventually hit OT_TIMEOUT (1501). Proactive handling of audioAcquisitionProblem can help avoid this downstream failure.