Skip to content

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+

  1. Install Missing Components:
  2. Python: Download from python.org

  3. Node.js: Download from nodejs.org

  4. 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

  1. Set Up API Keys:
  2. Copy env_template.txt to .env
  3. Add your API keys for Gemini, OpenAI, or other services

  4. Restart the backend server

  5. Verify API Keys:

  6. Test keys with simple requests
  7. 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

  1. Kill Conflicting Process: 

    taskkill /PID <process_id> /F

  2. Use Different Ports:

  3. Change ports in configuration files
  4. 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

  1. Verify API Configuration:
  2. Check API key validity
  3. Monitor API quota usage

  4. Test with simple prompts first

  5. Try Different Approaches:

  6. Use shorter, more focused prompts
  7. Break complex requests into smaller parts
  8. 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

  1. Use Persona System:
  2. Create or update your persona settings
  3. Ensure persona reflects your brand voice

  4. Test with different persona configurations

  5. Adjust Content Settings:

  6. Modify content length requirements
  7. Change content type or format
  8. 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

  1. Improve Research Queries:
  2. Use more specific search terms
  3. Include industry or topic context

  4. Try different keyword combinations

  5. Verify Research Services:

  6. Check search engine API configurations
  7. Monitor research service quotas
  8. 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

  1. Optimize Content Requests:
  2. Reduce content length requirements
  3. Use simpler prompts

  4. Disable unnecessary features

  5. Check API Response Times:

  6. Monitor API service status
  7. Try different AI service providers
  8. 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

  1. Clear Cache and Data: 

    # Clear browser cache
Ctrl + Shift + Delete

# Clear application cache
rm -rf node_modules/.cache

  2. 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

  1. 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()"

  2. Check Database Dependencies:

  3. Ensure SQLite is properly installed
  4. Update database models if needed
  5. 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

  1. Clear Application Cache:
  2. Clear browser local storage
  3. Reset application settings

  4. Restart all services

  5. Check Database Integrity:

  6. Verify database file isn't corrupted
  7. Check for database locking issues
  8. 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

  1. Verify Website Ownership:
  2. Ensure GSC property is verified
  3. Check domain/property configuration

  4. Verify website is properly indexed

  5. Test Connection:

  6. Try manual data import
  7. Check API endpoint accessibility
  8. 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

  1. Check Data Sources:
  2. Ensure GSC connection is active
  3. Verify website tracking is working

  4. Check for data processing delays

  5. Monitor API Limits:

  6. Check GSC API quota usage
  7. Implement data caching if needed
  8. 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

  1. Clear Browser Data:
  2. Clear cache and cookies
  3. Disable browser extensions

  4. Try incognito/private mode

  5. 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

  1. Verify API Connection:
  2. Check if backend is running
  3. Test API endpoints directly

  4. Verify CORS configuration

  5. 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!