GeolocationPositionError — Schnittstelle · JavaScript-Referenz

Signatur

interface GeolocationPositionError

Beschreibung

Ein GeolocationPositionError-Objekt bekommt der Fehler-Callback von navigator.geolocation.getCurrentPosition() und navigator.geolocation.watchPosition(), wenn kein Standort ermittelt werden konnte. Selbst erzeugen kann man es nicht, denn es gibt keinen öffentlichen Konstruktor. Die Instanzen erzeugt immer der Browser.

Die Schnittstelle hat zwei schreibgeschützte Eigenschaften:

code: eine Zahl, die den Fehlergrund angibt. Die Werte stehen als statische Konstanten zur Verfügung: PERMISSION_DENIED (1), POSITION_UNAVAILABLE (2) und TIMEOUT (3).
message: ein Text zur Fehlersuche. Inhalt und Sprache hängen vom Browser ab. Er ist nicht für Endnutzer gedacht.

In der Praxis wertet man code aus und reagiert passend: Bei einer Ablehnung bietet man z. B. eine manuelle Adresseingabe an, bei POSITION_UNAVAILABLE einen erneuten Versuch mit anderen Optionen und bei TIMEOUT einen höheren Wert für timeout oder enableHighAccuracy: false.

Wichtig: GeolocationPositionError erbt nicht von Error oder DOMException. Deshalb ergibt err instanceof Error den Wert false, und es gibt auch keinen Stacktrace.

Parameter

Name	Typ	Default	Beschreibung
$code Pflicht	number (1 \| 2 \| 3)		Schreibgeschützt. Fehlergrund: `1` = `PERMISSION_DENIED` (Nutzer oder Richtlinie hat abgelehnt), `2` = `POSITION_UNAVAILABLE` (interner Fehler oder kein Signal), `3` = `TIMEOUT` (die Zeit aus `options.timeout` ist abgelaufen).
$message Pflicht	string		Schreibgeschützt. Beschreibung des Fehlers durch den Browser, gedacht für Protokolle und Fehlersuche. Der Text ist nicht übersetzt und nicht einheitlich.

Rückgabewert

Typ

GeolocationPositionError

Beschreibung

Wird als einziges Argument an den Fehler-Callback von getCurrentPosition() bzw. watchPosition() übergeben.

Beispiele

Fehlercodes im Fehler-Callback auswerten

const onSuccess = (pos) => {
  const { latitude, longitude } = pos.coords;
  console.log(`Standort: ${latitude}, ${longitude}`);
};

const onError = (err) => {
  switch (err.code) {
    case GeolocationPositionError.PERMISSION_DENIED:
      console.warn('Zugriff auf den Standort wurde verweigert.');
      break;
    case GeolocationPositionError.POSITION_UNAVAILABLE:
      console.warn('Standort derzeit nicht verfügbar.');
      break;
    case GeolocationPositionError.TIMEOUT:
      console.warn('Zeitüberschreitung bei der Standortabfrage.');
      break;
  }
  console.debug('Details:', err.message);
};

navigator.geolocation.getCurrentPosition(onSuccess, onError, {
  enableHighAccuracy: true,
  timeout: 5000,
  maximumAge: 0
});

Zugriff auf den Standort wurde verweigert. Details: User denied Geolocation

Promise-Wrapper mit Fallback bei Zeitüberschreitung

const getPosition = (options) =>
  new Promise((resolve, reject) =>
    navigator.geolocation.getCurrentPosition(resolve, reject, options)
  );

const locate = async () => {
  try {
    return await getPosition({ enableHighAccuracy: true, timeout: 4000 });
  } catch (err) {
    if (err.code === GeolocationPositionError.TIMEOUT) {
      // Zweiter Versuch: ungenauer, aber schneller
      return getPosition({ enableHighAccuracy: false, timeout: 10000, maximumAge: 60000 });
    }
    throw err;
  }
};

locate()
  .then((pos) => console.log('Genauigkeit (m):', pos.coords.accuracy))
  .catch((err) => console.error(`Geolocation-Fehler ${err.code}: ${err.message}`));

Genauigkeit (m): 1200

watchPosition bei Ablehnung beenden

const watchId = navigator.geolocation.watchPosition(
  (pos) => console.log('Neue Position:', pos.coords.latitude, pos.coords.longitude),
  (err) => {
    console.log(err instanceof GeolocationPositionError); // true
    console.log(err instanceof Error);                    // false
    if (err.code === err.PERMISSION_DENIED) {
      navigator.geolocation.clearWatch(watchId);
      document.querySelector('#manual-location')?.removeAttribute('hidden');
    }
  }
);

true false

// Wichtig · Fallstricke

Nur in sicheren Kontexten: Die Geolocation-API funktioniert nur über HTTPS oder auf localhost. Auf HTTP-Seiten melden aktuelle Browser sofort PERMISSION_DENIED, ohne den Nutzer zu fragen.
Permissions-Policy: In einem <iframe> ohne allow="geolocation" endet die Abfrage ebenfalls mit Code 1.
Kein Error: Das Objekt erbt nicht von Error. instanceof Error ergibt false, es gibt keinen stack, und manche Fehler-Tracker erkennen es deshalb nicht. Wenn nötig, packt man es in ein eigenes Error-Objekt, z. B. new Error(err.message, { cause: err }).
message nicht anzeigen: Der Text ist je nach Browser verschieden, oft englisch und teilweise leer. Für die Oberfläche eigene Texte je nach code verwenden.
Ohne timeout kein TIMEOUT: Der Standardwert ist Infinity. Ohne eigenen Wert kann die Abfrage also beliebig lange hängen.
Alter Name: Früher hieß die Schnittstelle PositionError. Wer sehr alte Browser unterstützen muss, vergleicht besser direkt mit den Zahlen 1, 2 und 3 statt mit den statischen Konstanten.
Den Status der Berechtigung kann man vorher mit navigator.permissions.query({ name: 'geolocation' }) abfragen und so Code 1 schon vor der Abfrage erkennen.

Siehe auch

Geolocation Geolocation.getCurrentPosition() Geolocation.watchPosition() Geolocation.clearWatch() GeolocationPosition GeolocationCoordinates Permissions.query()