# Troubleshooting Guide

**Purpose:** Common issues, symptoms, causes, and solutions.  
**Owner:** Development Team  
**Last Updated:** 2025-12-22  
**Status:** active

---

## CI Failures

### Symptom: `./ci/run.sh` fails

**Causes:**
- Forbidden files in package
- Core module imports platform deps
- Export paths don't match artifacts

**Solutions:**
1. Check forbidden files: `npm pack --dry-run | grep -E "xcuserdata|xcuserstate|DerivedData|ios/App/"`
2. Check core purity: `grep -r "@capacitor\|react\|fs\|path\|os" src/core/`
3. Check exports: `node -e "const p=require('./package.json'); console.log(JSON.stringify(p.exports, null, 2))"`

---

## Packaging Failures

### Symptom: `npm pack` includes forbidden files

**Causes:**
- `package.json` `files` field is too permissive
- `.npmignore` is missing or incomplete

**Solutions:**
1. Review `package.json` `files` field (should be whitelist)
2. Add to `.npmignore`: `**/xcuserdata/`, `**/*.xcuserstate`, `**/DerivedData/`, `ios/App/`, `.DS_Store`
3. Run `npm pack --dry-run` to verify

---

## Platform Test Failures

### Symptom: Android tests fail in CI

**Causes:**
- Robolectric SDK version mismatch
- Missing test dependencies
- Test database setup issues

**Solutions:**
1. Check `@Config(sdk = [34])` matches Robolectric version
2. Verify `android/build.gradle` has test dependencies
3. Check `TestDBFactory` creates in-memory database correctly

### Symptom: iOS tests not running in CI

**Causes:**
- macOS runner not available
- xcodebuild not found
- Test app not configured

**Solutions:**
1. Use scheduled/manual workflows for iOS tests
2. Verify `xcodebuild` is available: `xcodebuild -version`
3. Check test app configuration in `test-apps/ios-test-app/`

---

## Build Failures

### Symptom: TypeScript compilation fails

**Causes:**
- Type errors in source code
- Missing type definitions
- Incorrect import paths

**Solutions:**
1. Run `npx tsc --noEmit` to see all type errors
2. Check import paths match `package.json` exports
3. Verify all dependencies are installed: `npm install`

### Symptom: Build succeeds but runtime errors occur

**Causes:**
- Missing runtime dependencies
- Incorrect module resolution
- Platform-specific code not available

**Solutions:**
1. Check `dist/` directory contains expected files
2. Verify `package.json` exports match build artifacts
3. Test on actual platform (not just build)

---

## Permission Issues

### Symptom: Notifications not appearing

**Causes:**
- Permission not granted
- Battery optimization killing background tasks
- Platform-specific permission issues

**Solutions:**
1. Check permission status: `await DailyNotification.checkPermission()`
2. Request permission: `await DailyNotification.requestPermission()`
3. Check battery optimization settings (Android)
4. Verify Info.plist/AndroidManifest.xml permissions

---

## Recovery Issues

### Symptom: Missed notifications after app restart

**Causes:**
- Recovery not running on app launch
- Database corruption
- Platform-specific recovery limitations

**Solutions:**
1. Check recovery logs in history: `await DailyNotification.getHistory({ kind: 'recovery' })`
2. Verify recovery is called on app launch
3. Check database integrity
4. Review platform-specific recovery constraints

---

## Performance Issues

### Symptom: Slow database queries

**Causes:**
- Large number of schedules
- Missing database indexes
- Database corruption

**Solutions:**
1. Check query performance in logs (warnings if > 100ms)
2. Review database schema for missing indexes
3. Consider database cleanup/migration

---

**See also:**
- [SYSTEM_INVARIANTS.md](./SYSTEM_INVARIANTS.md) — Enforced system invariants
- [PERFORMANCE.md](./PERFORMANCE.md) — Performance characteristics
- [docs/progress/03-TEST-RUNS.md](./progress/03-TEST-RUNS.md) — Test run history