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 Applications Complete guide to debugging Capacitor apps on iOS and Android. When to Use This Skill User reports app crashes User needs to debug WebView/JavaScript User needs to debug native code User has network/API issues User sees unexpected behavior User asks how to debug Quick Reference: Debugging Tools Platform WebView Debug Native Debug Logs iOS Safari Web Inspector Xcode Debugger Console.app Android Chrome DevTools Android Studio adb logcat WebView Debugging iOS: Safari Web Inspector 1. Enable on device : Settings Safari Advanced Web Inspector: ON Settings Safari Advanced JavaScript: ON 2. Enable in Xcode (capacitor.config.ts): 3. Connect Safari : Open Safari on Mac Develop menu [Device Name] [App Name] If no Develop menu: Safari Settings Advanced Show Develop menu 4. Debug : Console: View JavaScript logs Network: Inspect API calls Elements: Inspect DOM Sources: Set breakpoints Android: Chrome DevTools 1. Enable in config (capacitor.config.ts): 2. Connect Chrome : Open Chrome on computer Navigate to chrome://inspect Your device/emulator should appear Click "inspect" under your app 3. Debug features : Console: JavaScript logs Network: API requests Performance: Profiling Application: Storage, cookies Remote Debugging with VS Code Install "Debugger for Chrome" extension: Native Debugging iOS: Xcode Debugger 1. Open in Xcode : 2. Set breakpoints : Click line number in Swift/Obj C files Or use breakpoint set name methodName in LLDB 3. Run with debugger : Product Run (Cmd + R) Or click Play button 4. LLDB Console commands : 5. View crash logs : Window Devices and Simulators Select device View Device Logs Android: Android Studio Debugger 1. Open in Android Studio : 2. Attach debugger : Run Attach Debugger to Android Process Select your app 3. Set breakpoints : Click line number in Java/Kotlin files 4. Debug console : 5. Logcat shortcuts : View Tool Windows Logcat Filter by package: package:com.yourapp Console Logging JavaScript Side Native Side (iOS) Native Side (Android) Common Issues and Solutions Issue: App Crashes on Startup Diagnosis : Common causes : 1. Missing plugin registration 2. Invalid capacitor.config 3. Missing native dependencies Solution checklist : [ ] Run npx cap sync [ ] iOS: cd ios/App && pod install [ ] Check Info.plist permissions [ ] Check AndroidManifest.xml permissions Issue: Plugin Method Not Found Error : Error: "MyPlugin" plugin is not implemented on ios/android Diagnosis : Solutions : 1. Ensure plugin is installed: npm install @capgo/plugin name 2. Run sync: npx cap sync 3. Check plugin is registered (native code) Issue: Network Requests Failing Diagnosis : Common causes : 1. iOS ATS blocking HTTP : Add to Info.plist: 2. Android cleartext blocked : Add to capacitor.config.ts: 3. CORS issues : Use native HTTP: Issue: Permission Denied Diagnosis : iOS : Check Info.plist has usage descriptions: Android : Check AndroidManifest.xml: Issue: White Screen on Launch Diagnosis : 1. Check WebView console for errors (Safari/Chrome) 2. Check if dist/ folder exists 3. Verify webDir in capacitor.config.ts Solutions : Issue: Deep Links Not Working Diagnosis : iOS : Check Associated Domains entitlement and apple app site association file. Android : Check intent filters in AndroidManifest.xml. Performance Debugging JavaScript Performance iOS Performance (Instruments) 1. Product Profile (Cmd + I) 2. Choose template: Time Profiler: CPU usage Allocations: Memory usage Network: Network activity Android Performance (Profiler) 1. View Tool Windows Profiler 2. Select: CPU: Method tracing Memory: Heap analysis Network: Request timeline Memory Debugging JavaScript Memory Leaks Use Chrome DevTools Memory tab: 1. Take heap snapshot 2. Perform action 3. Take another snapshot 4. Compare snapshots iOS Memory (Instruments) Android Memory (LeakCanary) Add to build.gradle: Debugging Checklist When debugging issues: [ ] Check WebView console (Safari/Chrome DevTools) [ ] Check native logs (Xcode Console/Logcat) [ ] Verify plugin is installed and synced [ ] Check permissions (Info.plist/AndroidManifest) [ ] Test on real device (not just simulator) [ ] Try clean build ( rm rf node modules && npm install ) [ ] Verify capacitor.config.ts settings [ ] Check for version mismatches (capacitor packages) Resources Capacitor Debugging Guide: https://capacitorjs.com/docs/guides/debugging Safari Web Inspector: https://webkit.org/web inspector Chrome DevTools: https://developer.chrome.com/docs/devtools Xcode Debugging: https://developer.apple.com/documentation/xcode/debugging Android Studio Debugging: https://developer.android.com/studio/debug

debugging-capacitor