debugging-capacitor
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::ERRCLEARTEXTNOTPERMITTED, 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 openurlprivacypush, xcrun devicectl device process launchopenURL, 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
- 1.3K
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/cap-go/capgo-skills --skill debugging-capacitor- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads debugging-capacitor automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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|androidor"<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:
appUrlOpensilent, universal links open the app but do nothing, JSpause/resumeor 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
- 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. - Classify the layer:
- JS exception, failed fetch, bad route -> web layer: open the WebView inspector (Safari /
chrome://inspect). Seereferences/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. Seereferences/native-debugging.md. - Works on Android but not iOS after 8.5/Xcode 27, link/lifecycle related -> UIScene. See
references/uiscene-regressions.md.
- JS exception, failed fetch, bad route -> web layer: open the WebView inspector (Safari /
- Reproduce with a fresh sync:
npm run build && npx cap syncthen rebuild native. Stalepublic/assets and un-synced plugins cause most "works in browser, broken on device" reports. - 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 tagCapacitorand JS console underCapacitor/Console. Log commands live inios-android-logs. - Report the root cause and proposed fix to the user before invasive changes (deleting
ios//android/, editingproject.pbxproj, disabling ATS globally). - 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,--httpsflags are removed. - Capacitor 8.5 (stable):
npx cap run ios -l --host 192.168.1.68 --port 5173(add--httpsfor an https dev server). - Android emulator/USB:
--forwardPorts 5173:5173runsadb reversesohttp://localhost:5173works. - 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.cleartextincapacitor.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:
npx cap doctorshows matching@capacitor/core,cli,ios,androidversions.npm run build && npx cap synccompletes with no warnings about missing plugins.- Native console shows
⚡️ Loading app at capacitor://localhost...(iOS) / noCapacitor/Consoleerrors (Android). - WebView inspector console is clean on launch.
- 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 runbuilds Debug by default; iOS accepts--configuration Release, Android release builds go through Android Studio or Gradle). - 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 seepauseandresume. - Before shipping:
grep -n "server" capacitor.config.*shows nourl/cleartextleft 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
FAQ
What does the debugging-capacitor skill do?
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::ERRCLEARTEXTNOTPERMITTED, 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 openurlprivacypush, xcrun devicectl device process launchopenURL, 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).
How do I install debugging-capacitor?
Run npx skills add https://github.com/cap-go/capgo-skills --skill debugging-capacitor in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/debugging-capacitor/ (personal) or .claude/skills/debugging-capacitor/ (project).
Which AI agents can use debugging-capacitor?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is debugging-capacitor safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains debugging-capacitor?
It is published by cap-go in cap-go/capgo-skills. It has 1,345 recorded installs.
More from cap-go/capgo-skills
capacitor-best-practices
cap-go/capgo-skills
Review and set up Capacitor apps against current best practices (Capacitor 8.5 stable, 9 alpha via @next). Use for a Capacitor codebase review, capacitor.config.ts audit, new project setup, aligning @capacitor/core/cli/ios/android and plugin majors, plugin patterns (availability checks, checkPermissions/requestPermissions, error code handling, web fallbacks), or release prep; or on " " plugin is not implemented on ios, Could not find the web assets directory, platform has not been added yet, a dev server.url shipped to production, lost edits in android/app/src/main/assets/public, SPM vs CocoaPods, or AppDelegate/UIScene drift. Do not use for security audits (capacitor-security), performance (capacitor-performance), tests (capacitor-testing), crashes (debugging-capacitor), major upgrades (capacitor-app-upgrades), SPM migration (cocoapods-to-spm), UIScene adoption (capacitor-uiscene-migration), or live updates (capgo-live-updates).
ionic-design
cap-go/capgo-skills
Builds and reviews Ionic Framework UI in Capacitor apps (Ionic 9 current, Ionic 8 still common) - page structure (ion-header/ion-content/ion-footer), lists, modern form syntax (label/labelPlacement on ion-input/ion-select), sheet modals, tabs + ion-router-outlet, CSS variable theming, dark palettes (palettes/dark.system.css, .ion-palette-dark), iOS vs MD mode, and Ionic 8 - 9 breaking changes (React Router 6, Vue Router 5, Angular 18-22 zoneless, removed ion-picker-legacy, boolean autocorrect, npx @ionic/migrate). Use when writing Ionic components, theming an Ionic app, fixing platform-mode styling, or upgrading @ionic/react, @ionic/vue, @ionic/angular. Do not use for Konsta UI (konsta-ui), Tailwind setup (tailwind-capacitor), raw safe-area CSS (safe-area-handling), keyboard resize (capacitor-keyboard), or Ionic Appflow/Enterprise migrations (ionic-appflow-migration, ionic-enterprise-sdk-migration).
capacitor-plugins
cap-go/capgo-skills
Pick, install, and wire up Capacitor plugins for native features (camera, filesystem, geolocation, biometrics, in-app purchases, social login, SQLite, calendar, contacts, health, BLE, NFC, etc.). Covers official @capacitor/ packages (Capacitor 8.5 stable, 9 alpha on next) plus the 145-package @capgo/ index, native permission keys (Info.plist, AndroidManifest, variables.gradle minSdk), npx cap sync / cap ls verification, and errors like '"Camera" plugin is not implemented on ios', 'unable to find plugin', UNIMPLEMENTED, and OS-PLUG- codes. Use for "which plugin should I use for X", adding a plugin, or a plugin call failing after install. Do not use for push setup (capacitor-push-notifications), splash assets (capacitor-splash-screen), keyboard layout (capacitor-keyboard), deep links (capacitor-deep-linking), OTA updates (capgo-live-updates), upgrading plugin source code (capacitor-plugin-upgrades), or adding SPM to a plugin (capacitor-plugin-spm-support).
capacitor-testing
cap-go/capgo-skills
Testing guide for Capacitor apps and plugins. Covers web-layer unit and component tests with Vitest and mocked Capacitor plugins (vi.mock('@capacitor/core'), registerPlugin), Playwright for the web build, Appium E2E with NATIVEAPP / WEBVIEW context switching, native plugin unit tests with Swift Testing vs XCTest (what can migrate, CAPPluginCall patterns, xcodebuild test on a simulator) and Android JUnit, plus an agent-driven verification loop on simulators and devices (build, install, launch, screenshot, UI hierarchy, tap, logs) with xcrun simctl, xcrun devicectl, adb, Xcode MCP device tools, and live reload via npx cap run --url (Capacitor 9) or -l --host --port (Capacitor 8). Use when adding tests, mocking plugins, "does it work on device", verifying a UI change on a simulator, migrating XCTest to Swift Testing, or setting up test CI. Do not use for crash log capture (ios-android-logs), WebView debugging sessions (debugging-capacitor), or build pipelines (capacitor
safe-area-handling
cap-go/capgo-skills
Fixes notch, Dynamic Island, home indicator, display cutout, and system bar overlap in Capacitor apps. Covers viewport-fit=cover + env(safe-area-inset-), the Capacitor 8 SystemBars core plugin (insetsHandling, injected --safe-area-inset- CSS variables for Android WebView < 140, removal of android.adjustMarginsForEdgeToEdge), Android 15/16 enforced edge-to-edge (overlaysWebView and backgroundColor of @capacitor/status-bar no longer work at targetSdk 36), iOS contentInset, and insets that change at runtime on rotation, iPad/foldable resizable windows. Use when headers sit under the status bar, tab bars hide behind the gesture bar, env() returns 0 on Android, or layout broke after upgrading to Capacitor 8 / targetSdk 35+. Do not use for keyboard overlap (capacitor-keyboard), Ionic/Konsta component theming (ionic-design, konsta-ui), Tailwind utility setup (tailwind-capacitor), or iOS multi-window/resizability adoption (capacitor-ios-resizability).
capacitor-deep-linking
cap-go/capgo-skills
Implements and debugs deep links in Capacitor apps - custom URL schemes, iOS Universal Links (apple-app-site-association, Associated Domains entitlement), Android App Links (assetlinks.json, autoVerify), and routing via @capacitor/app appUrlOpen + App.getLaunchUrl(). Covers the Capacitor 8.5+ UIScene change where AppDelegate application(:open:options:) and continue userActivity stop being called and custom handling must move to SceneDelegate, plus cold vs warm launch testing. Use when links open Safari/Chrome instead of the app, appUrlOpen never fires, the launch URL is lost on cold start, or OAuth redirects do not return to the app. Do not use for the full UIScene migration (capacitor-uiscene-migration), push notification taps (capacitor-push-notifications), or social login plugin setup (capacitor-plugins).
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.