daily-notification-plugin/docs/TROUBLESHOOTING.md

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 — Enforced system invariants
• PERFORMANCE.md — Performance characteristics
• docs/progress/03-TEST-RUNS.md — Test run history