Common getUserMedia() Errors

Implementing getUserMedia() for audio and video capture is a standard part of modern web development, but it often comes with a variety of hardware and permission-related hurdles. From users lacking a webcam to devices being occupied by other applications, developers need to be prepared for several edge cases.

The Media Capture and Streams API defines specific error types to help you identify these issues and provide clear feedback to your users. Here are the most common errors and how they differ between browsers like Chrome and Firefox.

Common Error Comparison

The way errors are named can vary between browsers, though Firefox generally follows the W3C spec more closely.

Deep Dive into the Top 5 Errors

1. NotFoundError (DevicesNotFoundError)

This is thrown when the requested media track (audio or video) cannot be found. This happens if:

• The user doesn’t have a webcam or microphone.
• The recording device is disabled at the OS level.
• You are requesting both audio and video, but even one of them is missing.

2. NotReadableError (TrackStartError)

This occurs when the browser has permission to use the device, but cannot access it.

• On Windows: Usually means another app (like Skype or another browser tab) has exclusive control over the hardware.
• On macOS: Less common as hardware is often shared, but Firefox may still throw it if multiple tabs compete for the same resource.

3. OverconstrainedError (ConstraintNotSatisfiedError)

Thrown when your constraints object asks for something the hardware can’t provide—such as a specific high resolution or frame rate using the min or exact keywords.

• Tip: Use ideal values instead of exact to avoid this error; the browser will then pick the closest supported resolution.

4. NotAllowedError (PermissionDeniedError)

This is the most straightforward error. It triggers when the user explicitly clicks “Block” on the permission prompt or has globally disabled camera/mic access for your site in their browser settings.

5. TypeError

A TypeError occurs when the constraints object passed to the function is either empty or has both audio and video set to false. Essentially, you are calling the function without asking for anything.

How to Handle Errors in JavaScript

Using the promise-based syntax, you can catch and handle these errors gracefully to improve the user experience.

var constraints = { video: true, audio: true };

navigator.mediaDevices.getUserMedia(constraints)
  .then(function(stream) {
    /* Use the stream */
  })
  .catch(function(err) {
    console.log("Error details:", err);

    if (err.name == "NotFoundError" || err.name == "DevicesNotFoundError") {
      alert("No camera or microphone found.");
    } else if (err.name == "NotReadableError" || err.name == "TrackStartError") {
      alert("Device is already in use by another application.");
    } else if (err.name == "NotAllowedError" || err.name == "PermissionDeniedError") {
      alert("Permission denied. Please enable camera access.");
    } else if (err.name == "OverconstrainedError") {
      alert("Requested constraints are not supported by your hardware.");
    } else {
      alert("An unknown error occurred: " + err.name);
    }
  });