docs

SDK troubleshooting

The failures partners hit most, and what actually fixes them.

Install succeeded but the device doesn't connect to Helium hotspots

  1. Confirm you're in range of a Helium hotspot. The SDK installs an EAP-TLS profile keyed to a specific Hotspot 2.0 RCOI (consortium) and FQDN; only matching APs trigger it.
  2. Confirm getRemoteStatus() shows active: true for this subscriber.
  3. On iOS, open Settings → Wi-Fi and tap the (i) on the network. There should be an "EAP" line with your subscriber's CN. If not, the profile didn't fully install.
  4. Production only: confirm the device is running a production-built app. Profiles installed by development or staging builds reference different CAs and won't match production hotspots.

The install dialog never appears on iOS

The keychain access group doesn't match your entitlements. Verify in Xcode:

  • Capabilities → Keychain Sharing has the group $(AppIdentifierPrefix)com.apple.networkextensionsharing.
  • Provider config has keychainAccessGroup: '<TEAM_ID>.com.apple.networkextensionsharing'.

The Team ID is visible in Xcode under Signing & Capabilities. Don't paste your bundle ID here.

PERMISSION_DENIED on Android even after adding the permission

You added the permission to the manifest but didn't request it at runtime. The SDK requires ACCESS_FINE_LOCATION to be granted, not just declared.

import { PermissionsAndroid } from 'react-native';

const result = await PermissionsAndroid.request(
  PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION,
);
if (result === PermissionsAndroid.RESULTS.GRANTED) {
  await install(subscriberId);
}

isInstalled() returns true but getRemoteStatus() returns null

The certificate was revoked server-side, by you or by Helium, while the local profile is still present. Clear the local side:

await remove();

Then re-install if the user still wants the offload service.

The same subscriber sees a different certificate on every install

Expected. Each call to install() revokes the prior server-side certificate and issues a fresh one. If you want stable certificate identity, don't call install() again unnecessarily: gate it behind isInstalled() === false.

My API key works in curl but the SDK says API_UNAUTHORIZED

Likely culprits:

  • The environment doesn't match the key. Development keys don't work against production, and vice versa.
  • The key picked up whitespace or quotes from your env file. Trim it.
  • Your EXPO_PUBLIC_* variable isn't being inlined into the bundle (Expo only).

I see HTTP 429 in the logs

You're rate-limited. See rate limits & errors for the backoff strategy.

Still stuck?

Email Helium support with:

  • Your partner ID and environment.
  • The error code (for example PROFILE_INSTALL_FAILED) and the nativeError string.
  • The subscriberId you used, if it isn't PII.
  • A timestamp window for when the call happened, so support can correlate it to gateway logs.

The SDK doesn't yet surface the server-side X-Request-Id. TODO: once it does, include that in the support email; it's the fastest correlation key.