Troubleshooting Guide
Common issues and solutions for CleverSearch integration. Follow these steps to resolve problems and optimize your setup.
Quick Debugging Steps
1
Enable Debug Mode
Turn on debug mode to see detailed logging
- Add ?clever-search-debug=true to your URL
- Or set DEBUG_MODE: true in script configuration
- Check browser console for detailed logs
2
Check Network Requests
Verify API calls are working correctly
- Open browser Developer Tools
- Go to Network tab
- Look for requests to /api/v1/tracker/
- Check response status and content
3
Verify Configuration
Ensure all settings are correct
- Check SITE_ID matches dashboard
- Verify script URL is correct
- Confirm page URL is in sitemap
- Test with different browsers
4
Test Global API
Use the exposed global API for testing
- Open browser console
- Run window.LLMOptimizer.getStats()
- Try window.LLMOptimizer.refresh()
- Check for error messages
Common Issues & Solutions
Tracker Script
Script not loading
highSymptoms:
- No content injection
- Console errors
- Network failures
Solutions:
- Check if the script URL is accessible
- Verify your SITE_ID is correct
- Ensure the script is placed in the <head> section
- Check for ad blockers or security software
Content not injecting
mediumSymptoms:
- Page loads normally
- No FAQ sections
- Original titles unchanged
Solutions:
- Verify your site ID in the dashboard
- Check browser console for JavaScript errors
- Ensure the page URL matches your sitemap
- Try enabling debug mode
SPA navigation issues
mediumSymptoms:
- Content only loads on first page
- Route changes don't trigger updates
Solutions:
- Ensure script loads before your SPA framework
- Check if your framework is detected correctly
- Verify history API is available
- Try manual refresh with window.LLMOptimizer.refresh()
Content Injection
Wrong content placement
mediumSymptoms:
- Content appears in wrong location
- Overlapping with existing content
Solutions:
- Add proper CSS selectors to your HTML
- Check for conflicting CSS styles
- Use custom placement options in dashboard
- Verify container elements exist
Content being overwritten
mediumSymptoms:
- Injected content disappears
- Original content restored
Solutions:
- Check for JavaScript that modifies DOM
- Look for CSS that hides injected elements
- Verify timing of content injection
- Check for framework-specific issues
Performance issues
lowSymptoms:
- Slow page loading
- High network usage
Solutions:
- Check network tab for failed requests
- Verify script is loading asynchronously
- Monitor Core Web Vitals
- Consider server-side rendering for critical content
Sitemap Import
Sitemap not accessible
highSymptoms:
- Import fails
- 404 errors
- Empty page list
Solutions:
- Verify sitemap URL is publicly accessible
- Check sitemap returns 200 status code
- Ensure proper XML format
- Try uploading sitemap file directly
Invalid XML format
highSymptoms:
- Parse errors
- Missing pages
- Import warnings
Solutions:
- Validate XML syntax
- Check for proper encoding (UTF-8)
- Verify required XML elements
- Use online XML validator
Missing pages
mediumSymptoms:
- Not all pages imported
- Some URLs skipped
Solutions:
- Check sitemap includes all important pages
- Verify lastmod dates are recent
- Ensure pages are accessible
- Check for robots.txt restrictions
Performance Optimization Tips
Optimize Script Loading
Ensure the tracker script loads efficiently
- Use async and defer attributes
- Place script in <head> section
- Avoid blocking other resources
- Consider preloading for critical pages
Minimize Content Size
Keep injected content concise and relevant
- Focus on essential content only
- Avoid duplicate information
- Use structured data efficiently
- Monitor content performance
Cache Optimization
Leverage caching for better performance
- Enable browser caching
- Use CDN for script delivery
- Implement proper cache headers
- Monitor cache hit rates
Still Need Help?
If you're still experiencing issues after following this guide, our support team is here to help.