Wszystkie Skills / CAP-GO

cap-go/capgo-skills

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, permis…

Zobacz źródło

Jak używać

Skopiuj polecenie instalacji i sprawdź źródła przed instalacją we własnym środowisku agenta.
W oryginale sprawdź wymagane narzędzia, dane dostępowe i obsługiwane środowiska.
Opisz dane wejściowe i oczekiwany rezultat; porównaj wynik ze źródłami.

npx skills add https://github.com/cap-go/capgo-skills --skill debugging-capacitor

Przed rozpoczęciem

Instalacja nie obejmuje subskrypcji modelu, limitu API ani uprawnień do plików.
Gwiazdki i instalacje pokazują aktywność, a nie niezależny test jakości lub bezpieczeństwa.

Oryginalny dokument Skill

Treść z repozytorium z zachowaniem nagłówków, przykładów, kodu, tabel, linków i obrazów.

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

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

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.
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.
Report the root cause and proposed fix to the user before invasive changes (deleting ios//android/, editing project.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, --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:

npx cap doctor shows matching @capacitor/core, cli, ios, android versions.
npm run build && npx cap sync completes with no warnings about missing plugins.
Native console shows ⚡️ Loading app at capacitor://localhost... (iOS) / no Capacitor/Console errors (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 run builds 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 see pause and resume.
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

Powiązane zadania

z tego samego repozytorium

Więcej Skills

Wszystkie Skills

capacitor-plugins

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

instalacje: 2
GitHub Stars: 74
Aktualizacja: 17 paź

Zobacz szczegóły →

capacitor-ios-security-hardening

Audits and progressively hardens Xcode security build settings for a Capacitor iOS app (ios/App/App.xcodeproj, scheme App) and native plugin code (Swift/ObjC/C, Package.swift, podspec). Covers xcodebuild -showBuildSettings -json, security compiler warnings, static analyzer checkers (xcodebuild analyze), Xcode Enhanced Security (ENABLEENHANCEDSECURITY, com.apple.security.hardened-process entitlements, pointer authentication / arm64e, memory tagging soft mode), what is safe for a WKWebView hybrid

instalacje: 1
GitHub Stars: 74
Aktualizacja: 17 paź

Zobacz szczegóły →

capacitor-splash-screen

Guide to configuring splash screens in Capacitor apps including asset generation, animation, and programmatic control. Use this skill when users need to customize their app launch experience.

instalacje: 1
GitHub Stars: 72
Aktualizacja: 13 lip

Zobacz szczegóły →

capacitor-accessibility

Accessibility guide for Capacitor apps covering screen readers, semantic HTML, focus management, and WCAG compliance. Use this skill when users need to make their app accessible.

instalacje: 2
GitHub Stars: 68
Aktualizacja: 13 lip

Zobacz szczegóły →