Debugging Capacitor

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

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):

const config: CapacitorConfig = {  ios: {    webContentsDebuggingEnabled: true, // Required for iOS 16.4+  },};

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):

const config: CapacitorConfig = {  android: {    webContentsDebuggingEnabled: true,  },};

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:

// .vscode/launch.json{  "version": "0.2.0",  "configurations": [    {      "type": "chrome",      "request": "attach",      "name": "Attach to Android WebView",      "port": 9222,      "webRoot": "${workspaceFolder}/dist"    }  ]}

Native Debugging

iOS: Xcode Debugger

1. Open in Xcode:

npx cap open ios

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:

# Print variablepo myVariable
# Print object descriptionp myObject
# Continue executioncontinue
# Step overnext
# Step intostep
# Print backtracebt

5. View crash logs:
   • Window > Devices and Simulators
   • Select device > View Device Logs

Android: Android Studio Debugger

1. Open in Android Studio:

npx cap open android

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:

# Evaluate expressionmyVariable
# Run methodmyObject.toString()

5. Logcat shortcuts:
   • View > Tool Windows > Logcat
   • Filter by package: package:com.yourapp

Console Logging

JavaScript Side

// Basic loggingconsole.log('Debug info:', data);console.warn('Warning:', issue);console.error('Error:', error);
// Grouped logsconsole.group('API Call');console.log('URL:', url);console.log('Response:', response);console.groupEnd();
// Table formatconsole.table(arrayOfObjects);
// Timingconsole.time('operation');// ... operationconsole.timeEnd('operation');

Native Side (iOS)

import os.log
let logger = Logger(subsystem: "com.yourapp", category: "MyPlugin")
// Log levelslogger.debug("Debug message")logger.info("Info message")logger.warning("Warning message")logger.error("Error message")
// With datalogger.info("User ID: \(userId)")
// Legacy NSLog (shows in Console.app)NSLog("Legacy log: %@", message)

Native Side (Android)

import android.util.Log
// Log levelsLog.v("MyPlugin", "Verbose message")Log.d("MyPlugin", "Debug message")Log.i("MyPlugin", "Info message")Log.w("MyPlugin", "Warning message")Log.e("MyPlugin", "Error message")
// With exceptionLog.e("MyPlugin", "Error occurred", exception)

Common Issues and Solutions

Issue: App Crashes on Startup

Diagnosis:

# iOS - Check crash logsxcrun simctl spawn booted log stream --level debug | grep -i crash
# Android - Check logcatadb logcat *:E | grep -i "fatal\|crash"

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:

import { Capacitor } from '@capacitor/core';
// Check if plugin existsconsole.log('Plugins:', Capacitor.Plugins);console.log('MyPlugin available:', !!Capacitor.Plugins.MyPlugin);

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:

// Add request interceptorconst originalFetch = window.fetch;window.fetch = async (...args) => {  console.log('Fetch:', args[0]);  try {    const response = await originalFetch(...args);    console.log('Response status:', response.status);    return response;  } catch (error) {    console.error('Fetch error:', error);    throw error;  }};

Common causes:

1. iOS ATS blocking HTTP: Add to Info.plist:

<key>NSAppTransportSecurity</key><dict>    <key>NSAllowsArbitraryLoads</key>    <true/></dict>

2. Android cleartext blocked: Add to capacitor.config.ts:

server: {  cleartext: true, // Only for development!}

3. CORS issues: Use native HTTP:

import { CapacitorHttp } from '@capacitor/core';
const response = await CapacitorHttp.request({  method: 'GET',  url: 'https://api.example.com/data',});

Issue: Permission Denied

Diagnosis:

import { Permissions } from '@capacitor/core';
// Check permission statusconst status = await Permissions.query({ name: 'camera' });console.log('Camera permission:', status.state);

iOS: Check Info.plist has usage descriptions:

<key>NSCameraUsageDescription</key><string>We need camera access to scan documents</string>

Android: Check AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />

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:

# Rebuild web assetsnpm run build
# Sync to nativenpx cap sync
# Check configcat capacitor.config.ts

Issue: Deep Links Not Working

Diagnosis:

import { App } from '@capacitor/app';
App.addListener('appUrlOpen', (event) => {  console.log('Deep link:', event.url);});

iOS: Check Associated Domains entitlement and apple-app-site-association file.

Android: Check intent filters in AndroidManifest.xml.

Performance Debugging

JavaScript Performance

// Mark performanceperformance.mark('start');// ... operationperformance.mark('end');performance.measure('operation', 'start', 'end');
const measures = performance.getEntriesByName('operation');console.log('Duration:', measures[0].duration);

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)

# Run with Leaks instrumentxcrun instruments -t Leaks -D output.trace YourApp.app

Android Memory (LeakCanary)

Add to build.gradle:

debugImplementation 'com.squareup.leakcanary:leakcanary-android:2.12'

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