ios-android-logs

iOS and Android Logs for Capacitor Apps

Pick the log channel that actually carries the message you need, filter to the app, capture to a file, hand off to diagnosis.

When to Use

TRIGGER when:

• User asks how to view, stream, filter, or save device/simulator logs.
• console.log output or ⚡️ Capacitor lines are missing on iOS/Android.
• User needs a crash report (.ips, tombstone, ANR) from a device or simulator.
• Logcat or the unified log is too noisy; user wants only their app or plugin.
• A log command fails or misbehaves: --level error still shows everything, unable to find utility "devicectl", Error: Unexpected argument 'log', adb: no devices/emulators found.

Do not use:

• Interpreting the error and fixing the app -> debugging-capacitor.
• Production crash/ANR reporting (Sentry, Crashlytics, Datadog) -> capacitor-native-observability.
• AI agent log streaming via MCP servers -> capacitor-mcp.
• CPU/memory profiling -> capacitor-performance.
• UIScene lifecycle migration -> capacitor-uiscene-migration.

Where Capacitor Output Goes (the main trap)

Source	iOS	Android
Capacitor bridge messages (⚡️ Loading app at ..., ⚡️ To Native ->, errors)	stdout only (print)	logcat tag Capacitor and Capacitor/<Sub>
JS console.log/warn/error mirrored natively	stdout as ⚡️ [log] - ...	logcat tag Capacitor/Console as File: ... - Line N - Msg: ...
JS console, full fidelity (objects, stack traces)	Safari Web Inspector	chrome://inspect
Plugin/app code using os.Logger / NSLog	unified log (Console.app, log stream)	n/a
Plugin code using android.util.Log / Capacitor Logger	n/a	logcat
Native crash	.ips crash report	FATAL EXCEPTION in logcat + crash buffer; tombstone for native code

Consequences:

• On iOS, Console.app and log stream will not show Capacitor's ⚡️ lines or mirrored JS console. Use Xcode's console, xcrun simctl launch --console-pty, or xcrun devicectl device process launch --console.
• Mirroring obeys loggingBehavior (none | debug | production, default debug): Release builds produce no Capacitor logs unless set to production.
• The iOS process name is the executable (App in the Capacitor template), not the display name. Filter with process == "App".

Quick Commands

# iOS Simulator: Capacitor + JS console (stdout), relaunching the app
xcrun simctl launch --console-pty --terminate-running-process booted com.example.app

# iOS Simulator: unified log for the app (os_log / NSLog / system messages)
xcrun simctl spawn booted log stream --level debug --predicate 'process == "App"'

# iPhone: install + launch with stdout attached (Xcode 15+ devicectl)
xcrun devicectl list devices
xcrun devicectl device process launch --console --terminate-existing --device <id> com.example.app

# iPhone: unified log snapshot of the last 10 minutes
sudo log collect --device-udid <udid> --last 10m --output /tmp/iphone.logarchive
log show /tmp/iphone.logarchive --predicate 'process == "App"' --info --debug

# Android: only this app (re-run after each app restart, PID changes)
adb logcat --pid="$(adb shell pidof -s com.example.app)"

# Android: Capacitor + JS console only
adb logcat -s Capacitor:V Capacitor/Console:V

# Android: crashes only
adb logcat -b crash

Procedure

1. Identify target: Simulator/emulator vs physical device; Debug vs Release; which layer emitted the message (table above).
2. Check connectivity: xcrun simctl list devices booted, xcrun devicectl list devices (device must be unlocked, trusted, Developer Mode on), adb devices -l.
3. Clear and reproduce: adb logcat -c on Android; on iOS start the stream before relaunching the app.
4. Filter early by process/PID, then by subsystem/tag, then by text. Never paste unfiltered system logs into a conversation.
5. Save to a file (> app.log, .logarchive, adb bugreport) when the user needs to share it; redact tokens, emails, and auth headers before sharing outside the team.
6. Hand off the relevant lines to debugging-capacitor for root-cause work.

Error Handling

Message	Fix
--level error still shows every message	log stream --level only understands default, info, debug (it sets the floor, not a ceiling). Filter errors with --predicate 'messageType == error OR messageType == fault'.
xcrun: error: unable to find utility "devicectl"	Active dev dir is Command Line Tools. sudo xcode-select -s /Applications/Xcode.app/Contents/Developer.
Error: Unexpected argument 'log' (devicectl)	devicectl has no log streaming subcommand. Use --console for stdout, Console.app or log collect --device-udid for unified logs.
log collect fails with a permission error	Run with sudo; device must be unlocked and trusted.
No devices are booted. (simctl)	xcrun simctl boot "<device name>" or open Simulator.
adb: no devices/emulators found / unauthorized	Enable USB debugging, accept the RSA prompt, adb kill-server && adb start-server.
adb logcat --pid= prints everything / errors	App not running so pidof returned nothing. Launch the app first.
No Capacitor/Console lines on Android	loggingBehavior: 'none', or Release build with default debug.
JS logs show but objects print as [object Object]	Native mirroring stringifies; use the WebView inspector for structured output.

Verification

• iOS sim: launch with --console-pty, see ⚡️ Loading app at capacitor://localhost and a test console.log('log-check') as ⚡️ [log] - log-check.
• iOS device: same via devicectl device process launch --console.
• Android: adb logcat -s Capacitor/Console:V shows Msg: log-check.
• Unified log: a plugin Logger(subsystem: "com.example.app", category: "test").info("log-check") appears with --predicate 'subsystem == "com.example.app"' --level info.

References

Only load a reference when its topic is in play.

File	Load when
references/ios-logs.md	Unified log predicates, Console.app, log collect/log show, iOS crash reports via devicectl/Xcode, adding os.Logger to a plugin
references/android-logs.md	logcat buffers/formats/filters, Android Studio Logcat queries, ANRs, tombstones, bugreports, WebView (chromium) noise

Resources

• https://developer.apple.com/documentation/os/logging
• https://developer.apple.com/documentation/xcode/acquiring-crash-reports-and-diagnostic-logs
• https://developer.android.com/tools/logcat
• https://developer.android.com/studio/debug/logcat
• https://capacitorjs.com/docs/config