swadhin / opengrammar public

Swadhin Biswas

[email protected]
2026-02-28 02:45:26 +0600 committed NaN years ago
a44c736
commit a44c736
1 file changed
+225 -0
Showing 1 changed file+225-0
opengrammar/TROUBLESHOOTING.md
▼opengrammar/TROUBLESHOOTING.md
+225-0
@@ -0,0 +1,225 @@
1
+# 🔧 Quick Troubleshooting Guide
2
+
3
+## Issue: Extension Closes/Crashes
4
+
5
+### ✅ Fixed in Latest Version
6
+
7
+**What was fixed:**
8
+- Better error handling in content script
9
+- Reduced error notifications
10
+- Silent handling of non-critical errors
11
+
12
+**Update and reload:**
13
+```bash
14
+# Rebuild extension
15
+cd opengrammar/extension && npm run build
16
+
17
+# Reload in Chrome:
18
+# chrome://extensions/ → Click reload icon on OpenGrammar
19
+```
20
+
21
+---
22
+
23
+## Issue: Invalid Model Error
24
+
25
+### ❌ Problem: Using Invalid Groq Model
26
+
27
+**Invalid model:** `openai/gpt-oss-120b` (not a real Groq model)
28
+
29
+### ✅ Solution: Use Valid Groq Models
30
+
31
+**Valid Groq Models:**
32
+- `llama-3.1-70b-versatile` ✅ (Recommended)
33
+- `llama-3.1-8b-instant` ✅ (Fast)
34
+- `gemma2-9b-it` ✅
35
+- `mixtral-8x7b-32768` ✅
36
+
37
+**How to fix:**
38
+1. Click extension icon
39
+2. Select **Groq** provider
40
+3. Choose model: `llama-3.1-70b-versatile`
41
+4. Enter your Groq API key
42
+5. Save settings
43
+
44
+---
45
+
46
+## Issue: No Grammar Highlights
47
+
48
+### Possible Causes:
49
+
50
+1. **Backend not running**
51
+ ```bash
52
+ # Start backend
53
+ cd opengrammar/backend
54
+ npm run dev
55
+ ```
56
+
57
+2. **Wrong backend URL**
58
+ - Click extension icon
59
+ - Backend URL should be: `http://localhost:8787`
60
+ - Green dot = Connected ✅
61
+
62
+3. **Extension disabled for site**
63
+ - Check options page → Site-specific settings
64
+ - Make sure current site is not disabled
65
+
66
+4. **Text too short**
67
+ - Extension only checks text with 5+ characters
68
+
69
+---
70
+
71
+## Issue: API Key Not Working
72
+
73
+### For Groq:
74
+
75
+1. **Get API key from:** https://console.groq.com
76
+2. **Key format:** Should start with `gsk_`
77
+3. **Free tier:** 100 requests/day
78
+4. **Enter in extension:**
79
+ - Click icon → API Key field
80
+ - Paste key starting with `gsk_`
81
+
82
+### Test API Key:
83
+```bash
84
+cd opengrammar/backend
85
+node test-groq.js
86
+# Should show: ✅ Success!
87
+```
88
+
89
+---
90
+
91
+## Issue: Model Dropdown Shows Wrong Models
92
+
93
+### ✅ Fixed: Model lists now match providers
94
+
95
+**Groq models:**
96
+- llama-3.1-70b-versatile
97
+- llama-3.1-8b-instant
98
+- gemma2-9b-it
99
+- mixtral-8x7b-32768
100
+
101
+**If models don't update:**
102
+1. Reload extension in chrome://extensions/
103
+2. Clear browser cache
104
+3. Re-open popup
105
+
106
+---
107
+
108
+## Issue: "2 notes selected" Error
109
+
110
+### Cause:
111
+Text selection handling issue
112
+
113
+### ✅ Fixed:
114
+- Better null checks in background script
115
+- Safer tab messaging
116
+- Error handling for missing tabs
117
+
118
+### Workaround (if issue persists):
119
+1. Reload extension
120
+2. Refresh the page
121
+3. Try selecting text again
122
+
123
+---
124
+
125
+## Quick Test Checklist
126
+
127
+Test if everything works:
128
+
129
+```bash
130
+# 1. Backend running?
131
+curl http://localhost:8787/health
132
+# Expected: {"status":"healthy",...}
133
+
134
+# 2. Extension loaded?
135
+# Check chrome://extensions/ → OpenGrammar enabled
136
+
137
+# 3. Test grammar check
138
+# Type in text box: "me and him went"
139
+# Expected: Red underline appears
140
+
141
+# 4. Test rewrite
142
+# Select text → Right-click → "Rewrite with OpenGrammar"
143
+# Expected: Rewrite popup opens
144
+```
145
+
146
+---
147
+
148
+## Debug Mode
149
+
150
+### Enable Debug Logging:
151
+
152
+**Backend:**
153
+```bash
154
+cd opengrammar/backend
155
+DEBUG=true npm run dev
156
+```
157
+
158
+**Extension Console:**
159
+1. Open any page
160
+2. Press F12 → Console
161
+3. Look for OpenGrammar logs
162
+
163
+### Common Log Messages:
164
+
165
+| Message | Meaning |
166
+|---------|---------|
167
+| `Grammar check skipped` | Normal - text too short or not editable |
168
+| `Backend connection issue` | Backend not running or wrong URL |
169
+| `LLM Analysis Error` | API key invalid or rate limit |
170
+| `Settings saved` | ✅ Settings updated successfully |
171
+
172
+---
173
+
174
+## Reset Everything
175
+
176
+If nothing works, reset:
177
+
178
+```bash
179
+# 1. Clear extension settings
180
+# Extension icon → Settings → Reset All Settings
181
+
182
+# 2. Reload extension
183
+# chrome://extensions/ → Reload OpenGrammar
184
+
185
+# 3. Restart backend
186
+# Ctrl+C → npm run dev
187
+
188
+# 4. Re-test
189
+# Type: "me and him went to store"
190
+# Expected: Grammar highlights appear
191
+```
192
+
193
+---
194
+
195
+## Still Having Issues?
196
+
197
+### Collect Debug Info:
198
+
199
+1. **Extension version:**
200
+ - chrome://extensions/ → Note version number
201
+
202
+2. **Backend logs:**
203
+ ```bash
204
+ cd opengrammar/backend
205
+ npm run dev 2>&1 | tee backend.log
206
+ ```
207
+
208
+3. **Browser console:**
209
+ - F12 → Console → Copy errors
210
+
211
+4. **Test results:**
212
+ ```bash
213
+ curl http://localhost:8787/health
214
+ curl http://localhost:8787/providers
215
+ ```
216
+
217
+### Get Help:
218
+
219
+- Check `TESTING_GUIDE.md` for detailed testing
220
+- Check `GROQ_SETUP.md` for Groq-specific issues
221
+- Check `FEATURES_IMPLEMENTATION.md` for feature details
222
+
223
+---
224
+
225
+**Last Updated:** After commit `5eb7975` (Error handling improvements)
0
226