Diagnose getUserMedia OverconstrainedError

The short answer

An OverconstrainedError from getUserMedia means that at least one required constraint in your request could not be satisfied by any available device. Constraints are required when you write them with exact, min or max, including a deviceId given as exact. Plain values and values wrapped in ideal are treated as preferences: the browser picks the closest match instead of failing. The fix is almost always in your code. Read the error's constraint property to see which setting failed, then loosen it to ideal, remove it, or catch the error and retry with a simpler request.

Two conditions limit this answer. First, if you request audio and video in the same call, the failing constraint may belong to the camera side, and the whole call fails, so you get no microphone stream either. Second, applyConstraints on an existing track can reject with the same error. In that case the track keeps its previous settings rather than stopping.

What the error object tells you

The error's name is OverconstrainedError, and its constraint property names the setting that could not be met, such as deviceId, sampleRate or channelCount. Browsers may report only the first failing constraint they find, so fixing one can reveal another. The constraint property can also be empty in some browser versions, and message text varies between browsers, so do not rely on parsing the message. Other getUserMedia errors point to different causes, and it helps to rule them out early.

Error name | Usual meaning | Where to look next

OverconstrainedError | A required constraint cannot be met by any device | Your constraints object

NotFoundError | No device of the requested kind is available | Connection, operating system input list

NotAllowedError | Permission was denied by the user, browser settings or a permissions policy | Site permissions, operating system privacy settings, embedding page

NotReadableError | A device exists but could not be opened, often because it is in use or the operating system blocked it | Other apps using the microphone, drivers

TypeError | The request itself is invalid, for example audio and video both false | Shape of the constraints object

Isolating the cause step by step

Treat any suspected cause as a hypothesis until a test result supports it. Every step below only changes the request your page sends, so each one is reversible and nothing about the device or system configuration is altered.

Step 1: Log the complete error

try {
  const stream = await navigator.mediaDevices.getUserMedia(constraints);
} catch (err) {
  console.log(err.name, err.constraint, err.message);
  console.log(JSON.stringify(constraints));
}

If the name is OverconstrainedError and constraint is filled in, you have your first candidate. If the name is something else, use the table above rather than editing constraints. If constraint is empty, move to the baseline test and narrow it down manually.

Step 2: Run a baseline request with no constraints

const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const [track] = stream.getAudioTracks();
console.log(track.label, track.getSettings());

If this succeeds, the microphone, permission and browser path all work, and the problem lies in your constraints. If it fails with NotFoundError, the browser sees no microphone at all, so this is not a constraint problem. Skip ahead to the section on hardware and system causes. If it fails with NotAllowedError, resolve permission first, because constraint testing cannot proceed without it.

Step 3: Compare what you asked for with what the device reports

console.log(navigator.mediaDevices.getSupportedConstraints());
console.log(track.getSettings());
if (typeof track.getCapabilities === 'function') {
  console.log(track.getCapabilities());
}
const devices = await navigator.mediaDevices.enumerateDevices();
console.log(devices.filter(d => d.kind === 'audioinput'));

getSupportedConstraints lists the constraint names the browser recognises. It does not tell you what ranges a particular microphone supports. getCapabilities, where available, reports the ranges and options for the opened device, and getSettings reports what the browser actually chose. getCapabilities is not implemented in every browser. Where it is missing, rely on getSettings and on trial requests. The browser silently ignores constraint names it does not recognise, so a misspelled constraint never causes this error and also has no effect.

Step 4: Reintroduce constraints one at a time

Starting from the working baseline, add your original constraints back one at a time, keeping each as exact, min or max as before. The first addition that triggers OverconstrainedError is the confirmed cause. At that point, decide whether that setting truly has to be mandatory. If the original call also requested video, test audio-only and video-only separately to find out which side is failing.

Common causes with webcam microphones

• A stored deviceId sent as exact. Device IDs are specific to each origin and can change, for example after site data is cleared or in a different browser profile. A saved ID for a webcam microphone that has been unplugged or re-identified will match nothing.
• Device information requested before permission. Until the user grants access, enumerateDevices may return blank labels and limited identifiers, so an ID taken at that stage may not be usable.
• A required sampleRate the device or browser path does not offer.
• channelCount required to be 2 when the webcam microphone delivers one channel. Many webcam microphones are mono, so confirm this for your device with getSettings or getCapabilities rather than assuming it.
• Required sampleSize or latency values outside the device's reported range.
• A required groupId intended to pair the camera and its microphone that no longer matches after a reconnect.
• Camera-side constraints such as an exact width, height, frameRate or facingMode in a combined audio and video request.

A more forgiving request for speech capture

async function openMic(savedId) {
  const audio = {
    echoCancellation: true,
    noiseSuppression: true,
    autoGainControl: true,
    channelCount: { ideal: 1 }
  };
  if (savedId) {
    try {
      return await navigator.mediaDevices.getUserMedia({
        audio: { ...audio, deviceId: { exact: savedId } }
      });
    } catch (err) {
      if (err.name !== 'OverconstrainedError') throw err;
    }
  }
  return navigator.mediaDevices.getUserMedia({ audio });
}

This pattern keeps the device choice strict but has a fallback, so your code knows when the saved microphone is unavailable and can tell the user, instead of switching devices without notice. Using ideal for deviceId would avoid the error, but the browser might then pick a different microphone, such as a laptop's built-in one, without telling you. After any successful call, check the track's label and getSettings to confirm that the intended webcam microphone is the one capturing.

Several of these settings affect speech capture directly. Echo cancellation, noise suppression and automatic gain control are processing features applied by the browser or system. Requesting them as plain values lets the browser honour them where it can without failing where it cannot. Support differs between browsers, so read getSettings to see what was actually applied. If a downstream pipeline needs a specific sample rate, it is usually safer to accept what the device provides and resample with the Web Audio API than to make the rate mandatory. Speech intelligibility does not depend on the device delivering the highest rate it can.

When the cause is not a constraint

If the baseline request fails with NotFoundError, or the webcam microphone is missing from enumerateDevices, look outside your code. Check whether the operating system lists the microphone as an input, and whether its per-app microphone privacy setting allows the browser. Try another browser, another USB port and a reconnect. If the microphone appears in the operating system but not in one browser, the cause is that browser's settings or permissions. If it does not appear in the operating system on any port or on a second computer, a hardware or firmware fault is the likely explanation, and that is the point where contacting the manufacturer about service or replacement is justified.

Limits of this guide

No device-specific test data was available for this guide, so it does not state the supported sample rates, channel counts or latency ranges of any particular webcam. Those values should come from getCapabilities on your own hardware or from the manufacturer's documentation. Browser behaviour also varies by vendor and version, including whether the constraint property is populated and whether getCapabilities exists, so confirm the details in the browsers your users rely on.