Skip to main content

Troubleshooting Template

info

Copy this template when creating a new troubleshooting guide. Delete this info box in your copy.

[Category] Troubleshooting

Brief description of what types of issues this guide covers.

Quick Diagnostics​

A checklist to quickly identify common issues:

  • Check 1: e.g., Are environment variables set?
  • Check 2: e.g., Is the service running?
  • Check 3: e.g., Are there errors in the console?

Issue: [Issue Title - Describe the Symptom]​

Symptoms​

What the user sees or experiences:

  • Error message: Exact error message here
  • Behavior: Description of what happens
  • Where it occurs: e.g., Development, Production, specific browser

Environment​

  • Affected platforms: e.g., Windows, macOS, all
  • Affected versions: e.g., Electron 39.x, Node 20.x
  • Frequency: e.g., Always, intermittent, after specific action

Root Cause​

Why this happens (if known):

Explanation of the underlying cause.

Solution​

Option 1: [Solution Name]

# Commands to fix the issue
command --with-flags

Option 2: [Alternative Solution]

  1. Step one
  2. Step two
  3. Step three

Verification​

How to confirm the issue is resolved:

# Command to verify
verification-command

Expected output: Description or example

Prevention​

How to avoid this issue in the future:

  • Preventive measure 1
  • Preventive measure 2

Issue: [Another Issue Title]​

Symptoms​

Repeat the structure above for each issue...

Still Stuck?​

If none of the above solutions work:

  1. Collect information:

    • Full error message and stack trace
    • Steps to reproduce
    • Environment details (OS, Node version, etc.)

  2. Search existing resources:

    • Slack channels: #channel-name
    • Previous tickets/issues

  3. Ask for help:

    • Post in #channel-name with collected information
    • Tag relevant team members if urgent
  • [Link to related doc 1]
  • [Link to related doc 2]