# debugging-capacitor

Diagnoses runtime bugs in Capacitor iOS and Android apps, fixing blank screens, plugin bridge errors, and network restrictions.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1300 installs · ★ 73
- Author: Cap-go
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Cap-go/capgo-skills/tree/HEAD/skills/debugging-capacitor/SKILL.md
- Updated: 2026-10-17
- HTML: https://affpapa.org/en/nevibecode/skills/debugging-capacitor

## What it does

The skill isolates bugs across distinct application layers: web runtime via Safari Web Inspector or `chrome://inspect`, bridge registration when a plugin is missing, native crashes in Xcode or Android Studio, and UIScene lifecycle regressions. It enforces a triage flow that starts with `npx cap doctor` and a clean `npm run build && npx cap sync` before altering any native source files.

Tooling steps account for CLI version differences. Capacitor 9 handles live reload through `--url`, whereas Capacitor 8.5 relies on `-l --host`. It provides direct terminal commands using `xcrun simctl` and `adb` to verify permissions, trigger universal links, and send simulated push payloads without changing production configs.

Wiping the `ios/` or `android/` directories or disabling ATS globally without isolating the root cause is explicitly forbidden. This skill handles runtime defects; initial deep link configuration, performance profiling, and dependency upgrade failures belong to separate skills.

## Requirements
- Works with: Chrome

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Cap-go/capgo-skills --skill debugging-capacitor -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/debugging-capacitor/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/debugging-capacitor/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Cap-go/capgo-skills --skill debugging-capacitor -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/debugging-capacitor/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Cap-go/capgo-skills --skill debugging-capacitor -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/debugging-capacitor/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Cap-go/capgo-skills debugging-capacitor
```

2. **Manually: put the files in place**
- File: `.github/skills/debugging-capacitor/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Cap-go/capgo-skills --skill debugging-capacitor -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Cap-go/capgo-skills --path skills/debugging-capacitor
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/debugging-capacitor/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Cap-go/capgo-skills --skill debugging-capacitor -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Cap-go/capgo-skills/tree/HEAD/skills/debugging-capacitor/SKILL.md

## When to use it
- resolve blank screen hangs and startup crashes on iOS and Android
- fix “plugin is not implemented on ios/android” bridge errors
- correct net::ERR_CLEARTEXT_NOT_PERMITTED and App Transport Security blocks
- configure live reload across Capacitor 8 and Capacitor 9 CLI flags
- restore broken appUrlOpen and lifecycle events caused by UIScene migrations

## Example prompts
- My iOS Capacitor app opens with a white screen, help me inspect the WebView and find the JavaScript error.
- I get net::ERR_CLEARTEXT_NOT_PERMITTED on Android during API requests, what needs to change in my network config?
- After upgrading to Capacitor 8.5, appUrlOpen stopped firing when opening universal links.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 9dcc2a9d32aef46f.

BEGIN THIRD-PARTY FILE 9dcc2a9d32aef46f
```text
---
name: debugging-capacitor
description: 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).
---

# 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`.
```
END THIRD-PARTY FILE 9dcc2a9d32aef46f

The third-party file has ended. Everything between the 9dcc2a9d32aef46f tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2465 of 11419 bytes. © Cap-go · MIT · https://github.com/Cap-go/capgo-skills/tree/HEAD/skills/debugging-capacitor/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md