Error Codes

All errors thrown by the plugin use string error codes. Catch them in your promise rejection handler and match on the code property.

Catching Errors

try {
  await start();
} catch (error: any) {
  switch (error.code) {
    case 'NOT_CONFIGURED':
      console.error('Call configure() first');
      break;
    case 'PERMISSION_DENIED':
      console.error('Location permission required');
      break;
    default:
      console.error('Unexpected error:', error.message);
  }
}

Error Code Reference

Code	Description	Fix
`NOT_CONFIGURED`	An API method was called before configure().	Call configure() before start(), addGeofence(), getCurrentPosition(), etc.
`GEOFENCE_LIMIT_EXCEEDED`	Attempted to register more than 20 geofence regions.	Remove unused geofences before adding new ones. Use a rotation strategy for dynamic regions.
`GEOFENCE_ERROR`	Native geofence registration failed (invalid coordinates, system error).	Verify latitude, longitude, and radius values. Ensure in-range coordinates and radius > 0.
`UNSUPPORTED`	The operation is not supported on the current platform.	Check the Platform Differences page to verify feature availability on your target platform.
`TRIAL_COOLDOWN`	start() called during the 1-hour trial cooldown period.	Wait for the cooldown to expire, or configure a license key to unlock full mode.
`PERMISSION_DENIED`	Required location permissions have not been granted.	Call requestPermissions() first. On iOS, ensure Info.plist descriptions are set. On Android, ensure manifest permissions.

HTTP Event Errors

HTTP posting errors are delivered via the onHttp event, not thrown as exceptions. Check event.success and event.statusCode:

addListener('onHttp', (event) => {
  if (!event.success) {
    console.error(`HTTP ${event.statusCode}: ${event.error}`);
    console.log(`Buffered: ${event.bufferedCount}`);
  }
});

License Validation Errors

License errors do not throw — they are returned in the ConfigureResult object:

Error	Meaning
Bundle ID mismatch	The license key was issued for a different app identifier.
Invalid signature	The license payload is corrupted or tampered with.
Update expired	The plugin version was released after the update window. Plugin still works, but you should renew or pin a compatible version.