Troubleshooting
Solutions for common issues.
Extension Won't Load
Error: "Manifest file is missing or unreadable"
Make sure you selected the correct folder when loading unpacked. The manifest.json file must be at the root of the selected folder.
Error: "Could not load manifest"
- Check that manifest.json is valid JSON (no trailing commas)
- Ensure all referenced files exist (background.js, content.js, etc.)
- Verify icon files exist in the icons/ folder
Sidebar Not Appearing
The CRM panel doesn't show on WhatsApp Web
Check Extension Is Enabled
Go to chrome://extensions and make sure ChatFlow CRM is toggled ON.
Refresh WhatsApp Web
Close and reopen WhatsApp Web, or press Ctrl+Shift+R for a hard refresh.
Check for Errors
Open DevTools (F12) → Console tab. Look for any red error messages related to ChatFlow CRM.
Check for Conflicts
Other WhatsApp extensions may conflict. Try disabling other extensions temporarily.
Panel appears but is blank
This usually means the CSS loaded but JavaScript didn't execute properly. Check the browser console for error messages.
Contact Not Detected
If the CRM panel says "Select a WhatsApp chat" even when a chat is open:
- WhatsApp Web may have updated their DOM structure. The extension uses multiple CSS selectors as fallbacks.
- Try clicking on a different contact and then back.
- Refresh the page.
AI Features Not Working
"Please configure your AI API key"
You haven't set up an AI provider. Go to extension Settings and configure your API key. See the AI Setup Guide.
"OpenAI/Gemini API error: 401"
Your API key is invalid or expired. Generate a new key from your provider's dashboard.
"OpenAI API error: 429"
You've hit the rate limit. Wait a minute and try again. Consider adding billing or increasing your usage tier.
"OpenAI API error: 402" or "insufficient_quota"
Your account is out of credits. Add funds to your AI provider account.
"No messages found in chat"
The extension couldn't extract messages from the current chat. This can happen if:
- The chat has no visible messages
- WhatsApp is still loading messages
- DOM selectors have changed
Data Issues
Data not saving
- Check that the extension has the storage permission enabled
- Chrome storage has a quota (~10MB for local). If you have thousands of contacts, you may be hitting limits.
Restore failed
- Ensure the backup file is valid JSON
- The file must contain a contacts key
- Try opening the file in a text editor to verify it's not corrupted
Performance
Extension is slow or WhatsApp feels sluggish
- The MutationObserver is debounced (500ms) to minimize performance impact
- If you have many contacts (1000+), search and filter operations may be slightly slower
- AI requests are network-bound; speed depends on your AI provider and model
- Try closing and reopening the WhatsApp Web tab
Getting Support
If your issue isn't listed above:
- Check the browser console (F12 → Console) for error messages
- Note your browser name and version
- Take a screenshot of the issue
- Contact support with all the above information