Troubleshooting
This section contains guides for diagnosing and resolving common issues encountered in development, testing, and production.
Quick Reference
| Issue Category | Common Symptoms | Guide |
|---|---|---|
| App Corrupted | App can't be opened, shows a "corrupted" error modal | Integrity Checksum |
Troubleshooting Approach
When encountering an issue, follow this general approach:
- Identify: What exactly is failing? Gather error messages and logs
- Isolate: Is it reproducible? What changed recently?
- Research: Check this documentation, then search team channels/history
- Resolve: Apply the fix and verify
- Document: If it's a new issue, add it to the relevant troubleshooting guide
Adding New Troubleshooting Entries
When documenting a new issue, include:
- Clear title: Describe the symptom, not the cause
- Environment: Where does this occur? (dev, staging, production)
- Steps to reproduce: How to trigger the issue
- Root cause: Why it happens (if known)
- Solution: Step-by-step fix
- Prevention: How to avoid this in the future (if applicable)
Use the Troubleshooting Template as a starting point.
Environment-Specific Issues
- Development: Usually related to setup, dependencies, or environment variables
- Windows/Electron: Often related to certificate signing, or native modules
- Production: May involve deployment, configuration, or infrastructure