new OverconstrainedError() — Methode · JavaScript-Referenz

Signatur

new OverconstrainedError(constraint, message)

Beschreibung

Der Konstruktor OverconstrainedError() erzeugt ein Fehlerobjekt vom Typ OverconstrainedError, das von DOMException erbt. Der Browser selbst verwirft Promises von navigator.mediaDevices.getUserMedia() und MediaStreamTrack.prototype.applyConstraints() mit so einem Fehler, wenn eine zwingende Einschränkung (etwa exact, min oder max) mit keinem verfügbaren Gerät bzw. keiner Einstellung erfüllt werden kann.

Selbst ruft man den Konstruktor vor allem in drei Fällen auf: beim Testen und Mocken von Medien-Code, in eigenen Hüllfunktionen (Wrappern) um die Media-Capture-API, die sich wie der Browser verhalten sollen, und in Polyfills. Das erzeugte Objekt hat den name "OverconstrainedError". In der Eigenschaft constraint steht der Name der Einschränkung, die nicht erfüllt werden konnte.

Wenn du den Fehler abfängst, prüfst du am besten error.name === "OverconstrainedError" statt instanceof. Die Prüfung über den Namen funktioniert auch über Frame-Grenzen hinweg und in Browsern, die die Klasse nicht als globalen Konstruktor bereitstellen.

Parameter

Name	Typ	Default	Beschreibung
$constraint Pflicht	string		Name der Einschränkung, die nicht erfüllt werden konnte, z. B. `"width"`, `"facingMode"` oder `"deviceId"`. Später lesbar über `error.constraint`.
$message	string	""	Optionale, gut lesbare Fehlermeldung. Später lesbar über `error.message`.

Rückgabewert

Typ

OverconstrainedError

Beschreibung

Ein neues OverconstrainedError-Objekt (eine Unterklasse von DOMException) mit name = "OverconstrainedError" und den Eigenschaften constraint und message, die aus den übergebenen Argumenten stammen.

Beispiele

Fehlerobjekt erzeugen und untersuchen

const err = new OverconstrainedError('width', 'Keine Kamera unterstützt 4K-Auflösung');

console.log(err.name);
console.log(err.constraint);
console.log(err.message);
console.log(err instanceof DOMException);

OverconstrainedError width Keine Kamera unterstützt 4K-Auflösung true

Fehler von getUserMedia() abfangen

const startCamera = async () => {
  try {
    return await navigator.mediaDevices.getUserMedia({
      video: { width: { exact: 3840 }, facingMode: { exact: 'environment' } }
    });
  } catch (error) {
    if (error.name === 'OverconstrainedError') {
      console.warn(`Einschränkung nicht erfüllbar: ${error.constraint}`);
      // Rückfall auf weiche Einschränkungen
      return navigator.mediaDevices.getUserMedia({ video: { width: { ideal: 1280 } } });
    }
    throw error;
  }
};

const stream = await startCamera();
console.log(stream.getVideoTracks()[0].getSettings());

Einschränkung nicht erfüllbar: width { width: 1280, height: 720, ... }

Eigener Wrapper wirft OverconstrainedError

// Prüft vor applyConstraints(), ob die Bildrate überhaupt unterstützt wird
const setFrameRate = async (track, fps) => {
  const { frameRate } = track.getCapabilities();
  if (frameRate && fps > frameRate.max) {
    throw new OverconstrainedError('frameRate', `Maximal ${frameRate.max} fps möglich`);
  }
  await track.applyConstraints({ frameRate: { exact: fps } });
};

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [track] = stream.getVideoTracks();

try {
  await setFrameRate(track, 240);
} catch (e) {
  console.error(e.name, e.constraint, e.message);
}

OverconstrainedError frameRate Maximal 30 fps möglich

Mock für Unit-Tests

// Simuliert eine Kamera, die keine Rückkamera besitzt
const fakeMediaDevices = {
  getUserMedia: async (constraints) => {
    if (constraints.video?.facingMode?.exact === 'environment') {
      throw new OverconstrainedError('facingMode', 'Keine Rückkamera vorhanden');
    }
    return new MediaStream();
  }
};

fakeMediaDevices
  .getUserMedia({ video: { facingMode: { exact: 'environment' } } })
  .catch((e) => console.log(`${e.name}: ${e.constraint}`));

OverconstrainedError: facingMode

// Wichtig · Fallstricke

Browser-Kompatibilität: Chromium-Browser und Safari stellen den Konstruktor global bereit. Firefox liefert bei getUserMedia() zwar Fehler mit dem Namen "OverconstrainedError", stellt aber je nach Version keinen aufrufbaren globalen Konstruktor bereit. Prüfe deshalb vorher mit typeof OverconstrainedError === 'function', ob er existiert, und nutze sonst ersatzweise new DOMException(message, 'OverconstrainedError').
Ältere Browser (und frühere Entwürfe der Spezifikation) verwendeten eine Klasse MediaStreamError oder den Namen ConstraintNotSatisfiedError. Robuster Code prüft deshalb beide Namen.
Der Fehler tritt nur bei zwingenden Einschränkungen auf (exact, min, max). Weiche Werte wie ideal oder einfache Zahlen führen nie zu einem OverconstrainedError. Oft reicht es, auf weiche Einschränkungen umzusteigen.
Datenschutz: Über die Eigenschaft constraint ließen sich Informationen über die vorhandene Hardware erschließen (Fingerprinting). Browser melden den Fehler deshalb teilweise erst, nachdem der Nutzer den Zugriff erlaubt hat, oder lassen constraint leer.
Die Media-Capture-API ist nur in einem sicheren Kontext (HTTPS oder localhost) verfügbar.

Siehe auch

OverconstrainedError OverconstrainedError.constraint DOMException MediaDevices.getUserMedia() MediaStreamTrack.applyConstraints() MediaStreamTrack.getCapabilities() new EventTarget()