agentleFS
Sign inStart free
Cap-goCap-go/capgo-skills/skills/debugging-capacitor/SKILL.md

debugging-capacitor

Skill75 starsChanged 32 days agoMITView on GitHub

Diagnoses and fixes runtime bugs in Capacitor iOS/Android apps - white/blank screen on launch, startup crashes, `"X" plugin is not implemented on ios/android`, `net::ERR_CLEARTEXT_NOT_PERMITTED`, App Transport Security blocks, CORS on capacitor://localhost, permission denials, live reload not connecting, and Capacitor 8.5+ UIScene regressions (appUrlOpen, universal links, pause/resume silent because AppDelegate callbacks stopped). Covers Safari Web Inspector, chrome://inspect, Xcode/LLDB, Android Studio, `npx cap run --url` (Capacitor 9) vs `-l --host` (8), `xcrun simctl openurl|privacy|push`, `xcrun devicectl device process launch|openURL`, `xctrace`. Do not use for only reading device logs (ios-android-logs), the UIScene migration itself (capacitor-uiscene-migration), deep-link setup (capacitor-deep-linking), speed (capacitor-performance), crash SDKs (capacitor-native-observability), tests (capacitor-testing), or upgrades/build errors (capacitor-app-upgrades, cocoapods-to-spm).

  • Installs packages

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    After updating to Capacitor 8.5+ / Xcode 27: appUrlOpen silent, universal links open the app but do nothing, JS pause/resume or custom …

    line 18
  2. Very specific:

    Only need to stream, filter, or save logs or crash reports -> ios-android-logs.

    line 22
  3. Very specific:

    Never ship server.url / server.cleartext in capacitor.config.*.

    line 66
  4. Distinctive:

    After any fix, prove it:

    line 91
  5. Very specific:

    Before shipping: grep -n "server" capacitor.config.* shows no url/cleartext left over.

    line 98
  6. Distinctive:

    Only load a reference when its topic is in play.

    line 102

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

NeediOSAndroid
Inspect DOM/JS/networkSafari > Develop > device > appchrome://inspect/#devices
Native breakpointsXcode (npx cap open ios), LLDBAndroid Studio debugger (npx cap open android)
Run on target from CLInpx cap run ios --target <id>npx cap run android --target <id>
List targetsnpx cap run ios --listnpx cap run android --list
Open URL / deep linkxcrun 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.jsonsend a real FCM message
Launch with stdoutxcrun simctl launch --console-pty booted <appId>; device: xcrun devicectl device process launch --console --device <id> <appId>adb logcat
ProfileInstruments / 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 / symptomLikely causeFix
"Foo" plugin is not implemented on iosPlugin not in native project, or JS injection blockednpm 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 androidGradle not synced, or a service worker intercepts the pagenpx cap sync android, then File > Sync Project with Gradle Files. Disable/unregister service workers in the native build.
"Foo.bar()" is not implemented on webCalling a native-only method in the browserGuard with Capacitor.isNativePlatform() / Capacitor.isPluginAvailable('Foo').
⚡️ ERROR: Unable to load .../index.html / white screenwebDir wrong or never copiedBuild web, verify webDir matches output folder, npx cap copy.
White screen, no native errorJS crash before first render, or bad <base href> / absolute asset pathsInspect WebView console; use relative/root paths that resolve under capacitor://localhost / https://localhost.
net::ERR_CLEARTEXT_NOT_PERMITTEDAndroid 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 ATSUse HTTPS. For dev only: NSExceptionDomains for the dev host, not global NSAllowsArbitraryLoads.
CORS error from API on device onlyOrigin 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*UsageDescriptionAdd the key to ios/App/App/Info.plist.
Permission always denied on AndroidMissing <uses-permission> or user chose "Don't allow" twiceAdd to AndroidManifest.xml; guide user to settings.
No such module 'Capacitor' (Xcode)Opened .xcodeproj with CocoaPods, or SPM packages not resolvedPods: open App.xcworkspace, npx cap sync ios. SPM: File > Packages > Reset Package Caches. Deeper -> cocoapods-to-spm.
Unable to boot device in current state: BootedSimulator already runningNot an error; use booted as the device id.
appUrlOpen / universal links silent on iOS only after 8.5AppDelegate open url / continue userActivity no longer calledSee references/uiscene-regressions.md.
JS pause/resume stop firingCustom SceneDelegate missing proxy forwarding, or logic left in applicationDidEnterBackgroundSee 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.

FileLoad when
references/webview-inspection.mdAttaching Safari/Chrome inspectors, inspector shows no app, debugging release builds, early-startup JS errors
references/native-debugging.mdNative crash, breakpoints in plugins, LLDB, Android Studio debugger, Instruments/xctrace, memory leaks
references/device-cli.mdDriving simulators/devices from the terminal: install, launch, open URLs, permissions, push, app containers
references/uiscene-regressions.mdiOS deep links, universal links, cold-start URL, pause/resume, or AppDelegate code broken after Capacitor 8.5 / Xcode 27
references/common-failures.mdDetailed fixes for white screen, plugin not implemented, networking, permissions, live reload

Resources

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free