OverconstrainedError — Schnittstelle · JavaScript-Referenz

Signatur

interface OverconstrainedError extends DOMException

Beschreibung

OverconstrainedError ist eine Unterklasse von DOMException. Ein Promise wird mit diesem Fehler abgelehnt, wenn navigator.mediaDevices.getUserMedia() oder MediaStreamTrack.prototype.applyConstraints() Anforderungen erhält, die kein verfügbares Gerät erfüllen kann, zum Beispiel { width: { exact: 4096 } } bei einer Full-HD-Webcam.

Die wichtigste Eigenschaft ist constraint. Sie enthält den Namen der Einschränkung, an der die Anfrage gescheitert ist, etwa "width", "frameRate" oder "deviceId". Außerdem gibt es die von DOMException geerbten Eigenschaften name (immer "OverconstrainedError") und message. Mit constraint kann eine Anwendung gezielt reagieren: die betroffene Einschränkung lockern und die Anfrage wiederholen.

Der Fehler entsteht nur bei verpflichtenden Einschränkungen, also bei exact, min und max. Einfache Werte und ideal-Werte sind nur Wünsche. Der Browser wählt dann die nächstbeste Einstellung und wirft keinen Fehler. In der Praxis gilt daher: exact nur verwenden, wenn die Anwendung ohne diese Fähigkeit wirklich nicht funktioniert, und sonst ideal nutzen.

Parameter

Name	Typ	Default	Beschreibung
$constraint Pflicht	string		Nur für den Konstruktor `new OverconstrainedError(constraint, message)`: Name der Einschränkung, die nicht erfüllt werden konnte. Später über die Eigenschaft `error.constraint` lesbar.
$message	string	""	Nur für den Konstruktor: lesbare Fehlerbeschreibung, später über `error.message` lesbar.

Rückgabewert

Typ

OverconstrainedError

Beschreibung

Der Konstruktor liefert ein neues Fehlerobjekt mit name === "OverconstrainedError" und der übergebenen constraint-Eigenschaft. Normalerweise erzeugt man es nicht selbst, sondern bekommt es von einem abgelehnten Promise.

Beispiele

getUserMedia mit Rückfall auf geringere Auflösung

const startCamera = async () => {
  try {
    return await navigator.mediaDevices.getUserMedia({
      video: { width: { exact: 3840 }, height: { exact: 2160 } }
    });
  } catch (err) {
    if (err.name === 'OverconstrainedError') {
      console.warn(`Nicht erfüllbar: ${err.constraint}`);
      // Mit ideal-Werten erneut versuchen – wirft keinen OverconstrainedError
      return navigator.mediaDevices.getUserMedia({
        video: { width: { ideal: 1920 }, height: { ideal: 1080 } }
      });
    }
    throw err; // z. B. NotAllowedError weiterreichen
  }
};

const stream = await startCamera();
document.querySelector('video').srcObject = stream;

Nicht erfüllbar: width

applyConstraints auf laufendem Track

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

try {
  await track.applyConstraints({ frameRate: { min: 120 } });
} catch (err) {
  if (err.name === 'OverconstrainedError') {
    const caps = track.getCapabilities();
    console.log(`${err.constraint} max. möglich:`, caps.frameRate?.max);
    // Der Track behält seine bisherigen Einstellungen
    console.log('Aktuell:', track.getSettings().frameRate);
  }
}

frameRate max. möglich: 30 Aktuell: 30

Instanz selbst erzeugen (z. B. für Tests)

const err = new OverconstrainedError('deviceId', 'Kamera nicht gefunden');

console.log(err instanceof DOMException); // true
console.log(err.name);       // "OverconstrainedError"
console.log(err.constraint); // "deviceId"
console.log(err.message);    // "Kamera nicht gefunden"

true OverconstrainedError deviceId Kamera nicht gefunden

// Wichtig · Fallstricke

Prüfung über err.name: Ältere Firefox-Versionen haben den Fehler als MediaStreamError bzw. als allgemeine DOMException geliefert, nur mit name === "OverconstrainedError". Die Prüfung mit instanceof OverconstrainedError schlägt dort fehl oder löst sogar einen ReferenceError aus. Deshalb besser den Namen vergleichen.
Nur bei verpflichtenden Einschränkungen: Der Fehler entsteht nur bei exact, min und max. Ein häufiger Fehler ist { deviceId: { exact: gespeicherteId } } mit einer veralteten Geräte-ID, zum Beispiel wenn die Kamera abgesteckt wurde. Das Ergebnis ist ein OverconstrainedError mit constraint === "deviceId".
Datenschutz: Ein OverconstrainedError kann bei getUserMedia() schon auftreten, bevor der Nutzer die Berechtigung erteilt hat. Er verrät damit indirekt etwas über die vorhandene Hardware. Browser können deshalb die Details einschränken. Man sollte sich also nicht darauf verlassen, dass constraint immer gefüllt ist.
Nach einem gescheiterten applyConstraints(): Der Track bleibt unverändert und läuft mit den bisherigen Einstellungen weiter.
Sicherer Kontext: Die API funktioniert nur über HTTPS (oder localhost).
Ältere Spezifikation: Frühere Entwürfe nannten die Eigenschaft constraintName. Dieser Name ist veraltet.

Siehe auch

CSSContainerRule GPUInternalError GPUPipelineError OrientationSensor VideoTrackGenerator