#Troubleshooting and support

Start with read-only evidence. Do not repeatedly request permission, add every manifest capability, or request background access to solve a foreground issue.

#Triage by symptom

#1. Check the installation

yarn nitro-geolocation doctor

For a monorepo or CI artifact:

yarn nitro-geolocation doctor --project apps/mobile --json

Run it after the native project exists and after permission declarations are added. The doctor does not edit files. A clean JavaScript reinstall is not a substitute for rebuilding an app binary after native dependency changes.

#2. Capture foreground readiness

import {
  getLocationReadiness,
  getPermissionDetails,
} from 'react-native-nitro-geolocation';

const [permission, readiness] = await Promise.all([
  getPermissionDetails(),
  getLocationReadiness(),
]);

console.log({ permission, readiness });

These calls inspect state without acquiring a location. Use their normalized guidance/remediation fields in product UI rather than inferring prompt behavior from an OS name alone.

Then reproduce one explicit location request and record the structured error code and message. 2.0 API codes are strings; /compat codes remain numeric. Remove exact coordinates from logs before sharing them.

#3. Separate foreground and background failures

First confirm a foreground location through the quick start. Only then debug /background setup. Background tracking adds different permission, notification, service, persistence, and OS lifecycle contracts; it cannot repair a foreground provider failure.

For background evidence:

import {
  diagnoseBackgroundLocation,
  getBackgroundLocationStatus,
} from 'react-native-nitro-geolocation/background';

const [diagnosis, status] = await Promise.all([
  diagnoseBackgroundLocation(),
  getBackgroundLocationStatus(),
]);

console.log({ diagnosis, status });

Review the reliability contract before classifying termination, reboot, or suspension behavior as a library guarantee.

#Open a useful report

Use GitHub Discussions for integration questions and GitHub Issues for reproducible defects. This open-source project does not provide an SLA.

Include:

• exact Geolocation, Nitro Modules, React Native, React, and Expo versions;
• iOS/Android/browser version, device or simulator, and CPU architecture;
• CocoaPods/prebuilt/source-build path and whether a clean native rebuild ran;
• minimal main package, /compat, or /background import and options;
• doctor JSON plus permission/readiness or background diagnosis;
• expected result, actual result, and smallest reproduction steps;
• whether the problem happens in Debug, Release, and a physical device;
• a redacted native log around the failure.

Never post access tokens, HTTP-sync credentials, signing material, personal addresses, or precise user coordinates. Replace coordinates with coarse or synthetic values while preserving the relevant accuracy/timestamp metadata.

Do not report a security vulnerability in a public issue. Use the repository's private security advisory form.

#Before closing the investigation

• Reproduce with an exact dependency lockfile.
• Confirm the issue survives a native rebuild.
• Test the minimum permission set for the failing feature.
• Compare behavior with the repository's tested reference stack.
• Add a regression test or consumer scenario when the failure is fixed.