Comprehensive debugging guide for Capacitor applications. Covers WebView debugging, native debugging, crash analysis, network inspection, and common issues. Use this skill when users report bugs, crashes, or need help diagnosing issues.

Debugging Capacitor Apps Find which layer is broken (web, bridge, native, OS config), prove it with the right inspector, then fix the smallest thing. When to Use TRIGGER when: App shows a white/blank screen, crashes on launch, or freezes after a native call. Error "<Name " plugin is not implemented on ios android or "<Name .<method ()" is not implemented on ... . Network calls fail on device only: net::ERR CLEARTEXT NOT PERMITTED , ATS "requires the use of a secure connection", CORS errors. Permission prompts never appear or always deny. Live reload ( cap run url , server.url ) shows a blank page or "Webpage not available". After updating to Capacitor 8.5+ / Xcode 27: appUrlOpen silent, universal links open the app but do nothing, JS pause / resume or custom AppDelegate code no longer runs. User asks "how do I debug / inspect my Capacitor app". Do not use: Only need to stream, filter, or save logs or crash reports ios android logs . Performing the AppDelegate SceneDelegate migration itself capacitor uiscene migration . Setting up deep links, AASA, assetlinks from scratch capacitor deep linking . Jank, slow startup, bundle size, memory tuning capacitor performance . Sentry / Crashlytics / Datadog in production capacitor native observability . Writing unit/E2E tests capacitor testing . AI/MCP device automation capacitor mcp . Gradle/Xcode build failures from version bumps capacitor app upgrades ; Pods/SPM resolution cocoapods to spm . Push token/delivery issues capacitor push notifications ; keyboard overlap capacitor keyboard ; notch/insets safe area handling . Triage Workflow 1. Collect facts before touching code : platform(s), simulator vs device, debug vs release, Capacitor version ( npx cap doctor ), what changed last (upgrade, plugin added, config edit), exact error text. 2. Classify the layer : JS exception, failed fetch, bad route web layer: open the WebView inspector (Safari / chrome://inspect ). See references/webview inspection.md . plugin is not implemented bridge/registration: the native code is not in the binary or JS cannot be injected. See Error Handling below. Process dies / EXC BAD ACCESS / FATAL EXCEPTION native layer: run from Xcode / Android Studio with the debugger attached. See references/native debugging.md . Works on Android but not iOS after 8.5/Xcode 27, link/lifecycle related UIScene. See references/uiscene regressions.md . 3. Reproduce with a fresh sync : npm run build && npx cap sync then rebuild native. Stale public/ assets and un synced plugins cause most "works in browser, broken on device" reports. 4. Read the native console for Capacitor's own messages. iOS prints ⚡️ Loading app at ... , ⚡️ [log] ... , ⚡️ ERROR: Unable to load ... to stdout (visible in Xcode's console, simctl launch console pty , devicectl ... launch console ; not in Console.app). Android logs under tag Capacitor and JS console under Capacitor/Console . Log commands live in ios android logs . 5. Report the root cause and proposed fix to the user before invasive changes (deleting ios/ / android/ , editing project.pbxproj , disabling ATS globally). 6. Apply the fix, then run the Verification steps. Tool Matrix Need iOS Android Inspect DOM/JS/network Safari Develop device app chrome://inspect/ devices Native breakpoints Xcode ( npx cap open ios ), LLDB Android Studio debugger ( npx cap open android ) Run on target from CLI npx cap run ios target <id npx cap run android target <id List targets npx cap run ios list npx cap run android list Open URL / deep link xcrun simctl openurl booted <url ; device: xcrun devicectl device process openURL device <id <url adb shell am start W a android.intent.action.VIEW d "<url " <appId Reset/grant permissions (sim) xcrun simctl privacy booted reset all <appId adb shell pm revoke <appId android.permission.CAMERA / adb shell pm clear <appId Fake push (sim) xcrun simctl push booted <appId payload.json send a real FCM message Launch with stdout xcrun simctl launch console pty booted <appId ; device: xcrun devicectl device process launch console device <id <appId adb logcat Profile Instruments / xcrun xctrace record template 'Time Profiler' Android Studio Profiler Details and caveats: references/device cli.md . Live Reload Quick Path Capacitor 9 ( @next ): npx cap run ios url http://192.168.1.68:5173 . The old l/ live reload , host , port , https flags are removed. Capacitor 8.5 (stable): npx cap run ios l host 192.168.1.68 port 5173 (add https for an https dev server). Android emulator/USB: forwardPorts 5173:5173 runs adb reverse so http://localhost:5173 works. Dev server must bind to 0.0.0.0 ; phone and Mac on the same Wi Fi; iOS may ask for Local Network access; if denied the page never loads (re enable in Settings Privacy & Security Local Network). Never ship server.url / server.cleartext in capacitor.config. ; grep before release. Error Handling Error / symptom Likely cause Fix "Foo" plugin is not implemented on ios Plugin not in native project, or JS injection blocked npm i <plugin npx cap sync ios . SPM: check ios/App/CapApp SPM/Package.swift lists it; CocoaPods: check ios/App/Podfile . Remove WKAppBoundDomains from Info.plist or set ios.limitsNavigationsToAppBoundDomains: true . "Foo" plugin is not implemented on android Gradle not synced, or a service worker intercepts the page npx cap sync android , then File Sync Project with Gradle Files. Disable/unregister service workers in the native build. "Foo.bar()" is not implemented on web Calling a native only method in the browser Guard with Capacitor.isNativePlatform() / Capacitor.isPluginAvailable('Foo') . ⚡️ ERROR: Unable to load .../index.html / white screen webDir wrong or never copied Build web, verify webDir matches output folder, npx cap copy . White screen, no native error JS crash before first render, or bad <base href / absolute asset paths Inspect WebView console; use relative/root paths that resolve under capacitor://localhost / https://localhost . net::ERR CLEARTEXT NOT PERMITTED Android blocks HTTP (API 28+) Use HTTPS. For dev only: server.cleartext: true or a network security config.xml scoped to the dev host. "The resource could not be loaded because the App Transport Security policy requires the use of a secure connection." iOS ATS Use HTTPS. For dev only: NSExceptionDomains for the dev host, not global NSAllowsArbitraryLoads . CORS error from API on device only Origin is capacitor://localhost (iOS) / https://localhost (Android) Allow those origins server side, or enable CapacitorHttp ( plugins.CapacitorHttp.enabled: true ) to route fetch /XHR natively. Crash on permission request (iOS, This app has crashed because it attempted to access privacy sensitive data without a usage description ) Missing NS UsageDescription Add the key to ios/App/App/Info.plist . Permission always denied on Android Missing <uses permission or user chose "Don't allow" twice Add to AndroidManifest.xml ; guide user to settings. No such module 'Capacitor' (Xcode) Opened .xcodeproj with CocoaPods, or SPM packages not resolved Pods: open App.xcworkspace , npx cap sync ios . SPM: File Packages Reset Package Caches. Deeper cocoapods to spm . Unable to boot device in current state: Booted Simulator already running Not an error; use booted as the device id. appUrlOpen / universal links silent on iOS only after 8.5 AppDelegate open url / continue userActivity no longer called See references/uiscene regressions.md . JS pause / resume stop firing Custom SceneDelegate missing proxy forwarding, or logic left in applicationDidEnterBackground See references/uiscene regressions.md . More symptom specific fixes: references/common failures.md . Verification After any fix, prove it: 1. npx cap doctor shows matching @capacitor/core , cli , ios , android versions. 2. npm run build && npx cap sync completes with no warnings about missing plugins. 3. Native console shows ⚡️ Loading app at capacitor://localhost... (iOS) / no Capacitor/Console errors (Android). 4. WebView inspector console is clean on launch. 5. Re run the exact repro on both a simulator/emulator and a physical device, in a release build if the bug was release only ( cap run builds Debug by default; iOS accepts configuration Release , Android release builds go through Android Studio or Gradle). 6. For link/lifecycle fixes: test cold (app killed) and warm (app backgrounded) launch with simctl openurl / adb shell am start , and background/foreground once to see pause and resume . 7. Before shipping: grep n "server" capacitor.config. shows no url / cleartext left over. References Only load a reference when its topic is in play. File Load when references/webview inspection.md Attaching Safari/Chrome inspectors, inspector shows no app, debugging release builds, early startup JS errors references/native debugging.md Native crash, breakpoints in plugins, LLDB, Android Studio debugger, Instruments/xctrace, memory leaks references/device cli.md Driving simulators/devices from the terminal: install, launch, open URLs, permissions, push, app containers references/uiscene regressions.md iOS deep links, universal links, cold start URL, pause/resume, or AppDelegate code broken after Capacitor 8.5 / Xcode 27 references/common failures.md Detailed fixes for white screen, plugin not implemented, networking, permissions, live reload Resources https://capacitorjs.com/docs/ios/troubleshooting https://capacitorjs.com/docs/android/troubleshooting https://capacitorjs.com/docs/guides/live reload https://capacitorjs.com/docs/updating/8 5 https://capacitorjs.com/docs/cli/commands/run

debugging-capacitor