bdd2a5d7ac
P3.4-A: Enhanced public API JSDoc - Enhanced createSchedule() with detailed parameter docs and examples - Enhanced updateSchedule() with examples and error documentation - Enhanced deleteSchedule() with error documentation - Enhanced enableSchedule() with examples P3.4-B: Created troubleshooting guide - docs/TROUBLESHOOTING.md with common issues and solutions - Covers CI failures, packaging, platform tests, build, permissions, recovery, performance - Linked in docs/00-INDEX.md Verification: - TypeScript compiles ✅ - JSDoc generates in .d.ts files ✅ - Documentation created and linked ✅
152 lines
3.7 KiB
Markdown
152 lines
3.7 KiB
Markdown
# 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
|
|
|