add PWA Wrapper troubleshooting page

Author: UrazAkgultan

content/en/docs/refguide/mobile/pwa-wrapper/_index.md

@@ -31,6 +31,7 @@ This PWA Wrapper documentation section includes the following topics:
 * Limitations: [PWA Wrapper Limitations](/refguide/mobile/pwa-wrapper/pwa-wrapper-limitations/)
 * Deep linking guide: [PWA Wrapper Deep Linking](/refguide/mobile/pwa-wrapper/pwa-wrapper-deep-linking/) explains how to handle inbound and outbound deep links
 * Security and network access reference: [PWA Wrapper Security and Network Access](/refguide/mobile/pwa-wrapper/pwa-wrapper-security/) describes what the extension downloads, what local paths it scans, and which binaries it bundles
+* Troubleshooting: [Troubleshoot PWA Wrapper](/refguide/mobile/pwa-wrapper/pwa-wrapper-troubleshooting/) lists known issues and solutions
 
 ## Typical Use Cases
 

content/en/docs/refguide/mobile/pwa-wrapper/pwa-wrapper-troubleshooting.md

@@ -0,0 +1,52 @@
+---
+title: "Troubleshoot PWA Wrapper"
+url: /refguide/mobile/pwa-wrapper/pwa-wrapper-troubleshooting/
+weight: 60
+description: "Known issues and solutions for PWA Wrapper."
+---
+
+## Introduction
+
+This page describes known issues you may encounter when building or testing PWA Wrapper apps, along with the steps to resolve them.
+
+## Android
+
+### App Cannot Connect to localhost on a Physical Device{#android-localhost}
+
+**Symptom**: When you set the runtime URL to a localhost address (for example, `http://localhost:8080`) and install the app on a physical Android device, the app fails to load and shows the following error:
+
+```
+Page Load Error
+net::ERR_CACHE_MISS
+```
+
+{{< figure src="/attachments/refguide/mobile/pwa-wrapper/localhost-cache-miss-error.png" alt="Page Load Error showing net::ERR_CACHE_MISS on Android" max-width="400px" >}}
+
+**Cause**: Two things are required for a physical Android device to reach a localhost server on your machine:
+
+1. The app must have the `INTERNET` permission. Without it, the Android OS blocks all outbound network traffic.
+2. The device must have a port forwarding rule from its own localhost to your machine's localhost. Android devices do not forward ports automatically.
+
+**Solution**:
+
+1. In the PWA Wrapper builder, go to the **Permissions** step and enable the **INTERNET** permission.
+
+    For general guidance on permissions, see [Build PWA Wrapper Apps](/refguide/mobile/pwa-wrapper/build-pwa-wrapper-apps/).
+
+1. Connect the Android device to your machine via USB and make sure [USB debugging](https://developer.android.com/studio/debug/dev-options) is enabled on the device.
+
+1. Run the following ADB command to forward port 8080 from the device to your machine:
+
+    ```shell
+    adb reverse tcp:8080 tcp:8080
+    ```
+
+    If your Mendix runtime uses a different port, replace `8080` with the correct port number on both sides.
+
+1. Rebuild and reinstall the app with the localhost runtime URL.
+
+The app can now reach the Mendix runtime running on your development machine.
+
+{{% alert color="info" %}}
+The `adb reverse` rule applies only to the current USB session. You must re-run the command each time you reconnect the device or restart ADB.
+{{% /alert %}}

content/en/docs/refguide/mobile/using-mobile-capabilities/push-notifications/notif-pwa-wrapper.md

@@ -191,10 +191,6 @@ Create a new nanoflow (for example, `ACT_InitAppLifecycle`) and add the followin
 1. Set the parameters:
    * **onResume**: select the `ACT_RequestPushNotifications` nanoflow you created earlier
 
-The nanoflow is shown below:
-
-{{< figure src="/attachments/refguide/mobile/push-notifications/notif-pwa-wrapper/pwa-wrapper-lifecycle-nanoflow.png" alt="App lifecycle nanoflow calling ListenToAppLifecycle and ACT_RequestPushNotifications" max-width="80%" >}}
-
 ### Step 4: Add the Events Widget to the Home Page
 
 1. Open your app's default home page in Studio Pro.