ALwrity/docs-site/docs/user-journeys/content-creators/troubleshooting.md

Troubleshooting Guide

🎯 Overview

This troubleshooting guide covers common issues you might encounter while using ALwrity and provides step-by-step solutions to get you back on track quickly.

🚨 Common Issues and Solutions

Setup and Installation Issues

Issue: "Python not found" or "Node.js not found"

Symptoms: Error messages about missing Python or Node.js when trying to start ALwrity

Solutions:

1. Check Installation:

   python --version  # Should show Python 3.8+
   node --version    # Should show Node.js 18+
   

2. Install Missing Components:

   • Python: Download from python.org
   • Node.js: Download from nodejs.org

3. Restart Terminal: Close and reopen your terminal after installation

Issue: "API key not configured" errors

Symptoms: Content generation fails with authentication errors

Solutions:

1. Check Environment Variables:

   # In backend directory
   cat .env | grep API_KEY
   

2. Set Up API Keys:

   • Copy env_template.txt to .env
   • Add your API keys for Gemini, OpenAI, or other services
   • Restart the backend server

3. Verify API Keys:

   • Test keys with simple requests
   • Check API quotas and billing

Issue: "Port already in use" errors

Symptoms: Backend or frontend won't start due to port conflicts

Solutions:

1. Find Process Using Port:

   # For port 8000 (backend)
   netstat -ano | findstr :8000
   
   # For port 3000 (frontend)
   netstat -ano | findstr :3000
   

2. Kill Conflicting Process:

   taskkill /PID <process_id> /F
   

3. Use Different Ports:

   • Change ports in configuration files
   • Update frontend API endpoints if needed

Content Generation Issues

Issue: "No content generated" or empty responses

Symptoms: Content generation returns empty or minimal content

Solutions:

1. Check Input Quality:

   • Provide more detailed prompts
   • Include specific requirements and context
   • Use clear, descriptive language

2. Verify API Configuration:

   • Check API key validity
   • Monitor API quota usage
   • Test with simple prompts first

3. Try Different Approaches:

   • Use shorter, more focused prompts
   • Break complex requests into smaller parts
   • Try different content types (blog vs. social media)

Issue: "Content quality is poor" or irrelevant

Symptoms: Generated content doesn't match your requirements or is low quality

Solutions:

1. Improve Prompt Quality:

   • Be more specific about tone and style
   • Include examples of desired content
   • Specify target audience and goals

2. Use Persona System:

   • Create or update your persona settings
   • Ensure persona reflects your brand voice
   • Test with different persona configurations

3. Adjust Content Settings:

   • Modify content length requirements
   • Change content type or format
   • Enable research integration for better accuracy

Issue: "Research integration not working"

Symptoms: Content lacks research-backed information or sources

Solutions:

1. Enable Research Mode:

   • Toggle "Research Integration" in content settings
   • Ensure research services are configured
   • Check API keys for search services

2. Improve Research Queries:

   • Use more specific search terms
   • Include industry or topic context
   • Try different keyword combinations

3. Verify Research Services:

   • Check search engine API configurations
   • Monitor research service quotas
   • Test research functionality separately

Performance and Speed Issues

Issue: "Content generation is slow"

Symptoms: Long delays when generating content

Solutions:

1. Check System Resources:

   • Monitor CPU and memory usage
   • Close unnecessary applications
   • Ensure stable internet connection

2. Optimize Content Requests:

   • Reduce content length requirements
   • Use simpler prompts
   • Disable unnecessary features

3. Check API Response Times:

   • Monitor API service status
   • Try different AI service providers
   • Use faster content types (shorter posts vs. long articles)

Issue: "App crashes or freezes"

Symptoms: ALwrity becomes unresponsive or crashes

Solutions:

1. Check System Resources:

   • Monitor memory usage
   • Close other applications
   • Restart the application

2. Clear Cache and Data:

   # Clear browser cache
   Ctrl + Shift + Delete
   
   # Clear application cache
   rm -rf node_modules/.cache
   

3. Restart Services:

   # Stop all services
   Ctrl + C
   
   # Restart backend
   cd backend && python app.py
   
   # Restart frontend
   cd frontend && npm start
   

Database and Data Issues

Issue: "Database connection failed"

Symptoms: Error messages about database connectivity

Solutions:

1. Check Database File:

   • Ensure database files exist in backend directory
   • Check file permissions
   • Verify database isn't corrupted

2. Reset Database:

   # Backup existing data
   cp alwrity.db alwrity.db.backup
   
   # Remove and recreate database
   rm alwrity.db
   python -c "from models.database import init_db; init_db()"
   

3. Check Database Dependencies:

   • Ensure SQLite is properly installed
   • Update database models if needed
   • Run database migrations

Issue: "Data not saving" or "Settings not persisting"

Symptoms: Changes don't save between sessions

Solutions:

1. Check File Permissions:

   • Ensure write permissions on data directories
   • Check disk space availability
   • Verify file system integrity

2. Clear Application Cache:

   • Clear browser local storage
   • Reset application settings
   • Restart all services

3. Check Database Integrity:

   • Verify database file isn't corrupted
   • Check for database locking issues
   • Run database integrity checks

SEO and Analytics Issues

Issue: "Google Search Console not connecting"

Symptoms: Can't authenticate or import GSC data

Solutions:

1. Check Authentication:

   • Verify Google account permissions
   • Re-authenticate GSC connection
   • Check API quotas and limits

2. Verify Website Ownership:

   • Ensure GSC property is verified
   • Check domain/property configuration
   • Verify website is properly indexed

3. Test Connection:

   • Try manual data import
   • Check API endpoint accessibility
   • Monitor for error messages

Issue: "SEO data not updating"

Symptoms: SEO dashboard shows outdated information

Solutions:

1. Force Data Refresh:

   • Click "Refresh Data" in SEO dashboard
   • Check data update intervals
   • Verify API connection status

2. Check Data Sources:

   • Ensure GSC connection is active
   • Verify website tracking is working
   • Check for data processing delays

3. Monitor API Limits:

   • Check GSC API quota usage
   • Implement data caching if needed
   • Optimize data request frequency

Browser and Frontend Issues

Issue: "Page not loading" or "White screen"

Symptoms: Frontend doesn't load or shows blank page

Solutions:

1. Check Browser Console:

   • Open Developer Tools (F12)
   • Look for JavaScript errors
   • Check network request failures

2. Clear Browser Data:

   • Clear cache and cookies
   • Disable browser extensions
   • Try incognito/private mode

3. Check Frontend Build:

   cd frontend
   npm install
   npm run build
   npm start
   

Issue: "Features not working" in browser

Symptoms: Buttons don't respond or features are disabled

Solutions:

1. Check JavaScript Errors:

   • Open Developer Tools console
   • Look for error messages
   • Check for missing dependencies

2. Verify API Connection:

   • Check if backend is running
   • Test API endpoints directly
   • Verify CORS configuration

3. Update Dependencies:

   cd frontend
   npm update
   npm install
   

🔧 Advanced Troubleshooting

Log Analysis

Backend Logs

# Check backend logs
tail -f backend/logs/alwrity.log

# Check specific error types
grep -i error backend/logs/alwrity.log
grep -i exception backend/logs/alwrity.log

Frontend Logs

# Check browser console
# Open Developer Tools (F12) and check Console tab

# Check network requests
# Open Developer Tools > Network tab

System Diagnostics

Check System Resources

# Check memory usage
free -h  # Linux/Mac
wmic OS get TotalVisibleMemorySize,FreePhysicalMemory /format:table  # Windows

# Check disk space
df -h  # Linux/Mac
dir C:\  # Windows

Network Diagnostics

# Test internet connectivity
ping google.com

# Check DNS resolution
nslookup google.com

# Test API endpoints
curl -I https://api.example.com/health

Configuration Verification

Environment Variables

# Check all environment variables
env | grep ALWRITY

# Verify specific configurations
echo $API_KEY
echo $DATABASE_URL

Service Status

# Check if services are running
ps aux | grep python  # Backend
ps aux | grep node    # Frontend

# Check port usage
netstat -tulpn | grep :8000  # Backend port
netstat -tulpn | grep :3000  # Frontend port

🆘 Getting Additional Help

Self-Help Resources

1. Documentation: Check the main documentation for detailed guides
2. GitHub Issues: Search existing issues for similar problems
3. Community Forums: Ask questions in the community discussions
4. Video Tutorials: Watch step-by-step setup and usage guides

Reporting Issues

When reporting issues, please include:

1. Error Messages: Exact error text and screenshots
2. Steps to Reproduce: Detailed steps that led to the issue
3. System Information: OS, browser, Python/Node versions
4. Log Files: Relevant log entries and error traces
5. Expected vs. Actual Behavior: What you expected vs. what happened

Contact Support

• GitHub Issues: Create detailed issue reports
• Community Discord: Join for real-time help
• Email Support: For urgent or complex issues
• Documentation: Check for updates and new guides

📋 Prevention Tips

Regular Maintenance

1. Keep Software Updated: Regularly update Python, Node.js, and dependencies
2. Monitor System Resources: Ensure adequate memory and disk space
3. Backup Data: Regularly backup your database and configuration files
4. Check Logs: Periodically review logs for potential issues

Best Practices

1. Use Stable Internet: Ensure reliable internet connection for API calls
2. Monitor API Quotas: Keep track of API usage and limits
3. Test Changes: Test new features in development before production
4. Document Configuration: Keep notes of your setup and customizations

---

Still having issues? Check our GitHub Issues or join our Community Discussions for additional support!