Troubleshooting
Inspect the logs
On a connected device:
adb logcat -s TrackingSdkModule ReactNativeJS
Symptoms and error codes
| Symptom / code | What to check |
|---|---|
| Maven 401 / 403 or dependency resolution failure | Repository access, Gradle credential properties, repository URL and artifact version |
TrackingSdk native module not found | Both bridge files copied, package registered once, correct namespace / imports, full Android rebuild |
Unresolved BuildConfig.TRACKING_* | All six fields defined in the app module, buildConfig = true, correct BuildConfig import |
USERNAME_REQUIRED | Supply a nonblank username |
INVALID_DISTANCE_FILTER | Supply a finite number >= 0 |
CALLER_ACCESS_TOKEN_REQUIRED | Supply a nonblank token when skipLoginAndRegistration is true |
SDK_CONFIGURATION_ERROR | Check the required BuildConfig values for the selected authentication mode |
INIT_SDK_ERROR | Inspect the initialization error, backend configuration, authentication and registration |
START_TRACKING_ERROR | Inspect the SDK error, permissions, device location services and foreground activity |
INIT_START_EXCEPTION / "Current activity is null" | Call from an active foreground screen; inspect the native exception |
STOP_TRACKING_ERROR / STOP_TRACKING_EXCEPTION | Inspect the SDK stop error and activity availability |
GET_STATE_ERROR / GET_STATE_EXCEPTION | The native state query failed; the TypeScript wrapper masks it as false |
DEVICE_HEALTH_ERROR | The native health query failed; the wrapper returns null |
| Tracking enabled but no server records | Network access, push endpoint, token validity, username / tenant, backend logs |
| Background access still denied | Grant background access separately in settings, then retry after returning |
| Method "is not available in Android native module" | See Available API - several wrapper methods are not implemented on Android |
Validate on a physical device
A resolved startup Promise does not prove delivery. Before release, check on a real Android device:
- Start from a visible screen, grant permissions, and confirm the tracking state becomes enabled.
- Confirm locations arrive in the backend for the expected username and tenant.
- Move the device and test background and screen-off behaviour.
- Stop tracking and confirm the state becomes disabled.
- Test permission denial, approximate location, disabled location services, and returning from settings.
- Test relaunch, connectivity loss and recovery, and token expiry against your backend's expected behaviour.
- Validate the signed release build and any code-shrinking configuration separately - the example app disables release minification.
See also: Get Started.
