> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pushctl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Capacitor troubleshooting

> Resolve native synchronization, Firebase, APNs, permission, listener, and state issues.

<AccordionGroup>
  <Accordion title="The Pushctl plugin is not implemented">Run `npx cap sync`, then rebuild the native app. Browser-only execution has no native push implementation.</Accordion>
  <Accordion title="Android does not register">Check `google-services.json`, the Google Services plugin, Maven Central, and the Android package ID configured in Pushctl.</Accordion>
  <Accordion title="iOS does not register">Enable Push Notifications and add both APNs registration callbacks to `AppDelegate.swift` as shown in [native setup](/sdks/capacitor/native-setup). Confirm the APNs environment, then rebuild after syncing the plugin.</Accordion>
  <Accordion title="APNs returns BadDeviceToken on iOS">Match the Pushctl environment to the installed app: development-signed Xcode builds use Sandbox, while TestFlight and App Store builds use Production. See the [iOS FAQ](/sdks/ios/faq).</Accordion>
  <Accordion title="waitForRegistration times out on iOS">The host app probably did not post `.capacitorDidRegisterForRemoteNotifications` or `.capacitorDidFailToRegisterForRemoteNotifications`. Add both callbacks, then test on a device with valid APNs entitlements.</Accordion>
  <Accordion title="waitForRegistration reports a native error">On iOS, inspect the forwarded APNs error and verify entitlements. On Android, verify Firebase initialization and `google-services.json`.</Accordion>
  <Accordion title="Registration fails after a native token is received">Check network access, the Client token, application platform configuration, and the API error. A native token alone does not mean the Pushctl API accepted the installation.</Accordion>
  <Accordion title="getSubscriptionState rejects">Call and await `initialize` before reading state.</Accordion>
  <Accordion title="Events fire more than once">Retain and remove listener handles when views unmount, or call `removeAllListeners` before rebuilding the listener set.</Accordion>
  <Accordion title="Background iOS events are missing">Add the native Notification Service Extension and configure the same App Group in both targets and `initialize`.</Accordion>
  <Accordion title="Login or logout rejects">Wait for `waitForRegistration()` first. These methods reject when the installation is not registered or the Pushctl API update fails.</Accordion>
  <Accordion title="The user remains associated after app logout">Call and await `Pushctl.logout()` as part of the app's sign-out flow. Do not discard a rejected promise.</Accordion>
</AccordionGroup>