# VOTD — Crash Log Guide

How to retrieve and read crash logs from a physical device.

---

## Fastest method — Xcode Console (live, on crash)

Use this when the app is crashing on launch or during a reproducible action.

1. Plug iPhone into Mac via USB
2. Open Xcode → **Window → Devices and Simulators**
3. Select the iPhone in the left panel
4. Click **Open Console** at the bottom
5. In the Console search box (top right), type `VOTD`
6. Set the filter dropdown next to the search box to **process** (not "any")
7. Launch the app on the phone
8. The crash reason appears in the last few lines before the process terminates

The line to look for is either:
- `error ... Unhandled JS Exception: ...` — JavaScript crash, shows the exact error message
- `fault ... EXC_CRASH (SIGABRT)` — native crash, needs the `.ips` file to decode

---

## Pulling crash reports off the device

Use this when a crash happened earlier and you need the full stack trace.

```bash
idevicecrashreport -e -k ~/Desktop/crashlogs
```

This pulls all crash `.ips` files from the device onto your Desktop. Find the most recent `votd-*.ips` file and share it for analysis.

If `idevicecrashreport` is not installed:
```bash
brew install libimobiledevice
```

---

## Reading a crash file

Open the `.ips` file in a text editor and look for these fields:

**JS crash** — look for this near the top:
```
"asi": { ... "Unhandled JS Exception: ..." }
```
or in the log stream output:
```
error   VOTD   Unhandled JS Exception: Invariant Violation: ...
```

**Native crash** — look for:
```
"exception": { "type": "EXC_CRASH", "signal": "SIGABRT" }
"triggered": true   ← this thread is the one that crashed
```
Then read the `"frames"` array on the triggered thread for the call stack.

---

## Common crashes and fixes

| Error message | Cause | Fix |
|---|---|---|
| `TurboModuleRegistry.getEnforcing(...): 'WatchConnectivity' could not be found` | Native pod not installed in binary | Use `watchConnectivityStub.ts` instead of real package until pod is installed |
| `Invariant Violation: Text strings must be rendered within a <Text> component` | Bare string in JSX outside `<Text>` | Find the component and wrap in `<Text>` |
| `Cannot read property 'X' of undefined` | Module loaded before native bridge ready | Wrap in `try/catch` or defer with `useEffect` |
| `EXC_CRASH (SIGABRT)` on `ExceptionsManagerQueue` | Unhandled JS error reached top-level handler | Find the JS error in Xcode Console (method above) |

---

## What does not work

- `log stream --device` — `--device` flag not supported on all Mac OS versions
- `xcrun simctl` commands — only work for simulators, not physical devices
- `log stream --predicate 'process == "votd"'` — does not attach to TestFlight/ad-hoc builds reliably

Use the **Xcode Console method** above. It is the most reliable for production builds on physical devices.