Troubleshooting Guide¶

This guide helps you resolve common issues with ALwrity. If you don't find your issue here, please check our GitHub Issues or create a new one.

Common Issues¶

Backend Issues¶

Server Won't Start¶

Symptoms: Backend server fails to start or crashes immediately

Solutions: 1. Check Python Version:

python --version
# Should be 3.10 or higher

Verify Dependencies:

cd backend
pip install -r requirements.txt

Check Port Availability:

# Check if port 8000 is in use
netstat -an | findstr :8000

Environment Variables:

# Ensure .env file exists with required keys
GEMINI_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here

Database Connection Errors¶

Symptoms: Database connection failures or SQL errors

Solutions: 1. Check Database File:

# Ensure database file exists
ls -la backend/alwrity.db

Reset Database:

cd backend
rm alwrity.db
python -c "from services.database import initialize_database; initialize_database()"

Check Permissions:

# Ensure write permissions
chmod 664 backend/alwrity.db

API Key Issues¶

Symptoms: 401/403 errors, "Invalid API key" messages

Solutions: 1. Verify API Keys:

# Check .env file
cat backend/.env | grep API_KEY

Test API Keys:

# Test Gemini API
curl -H "Authorization: Bearer $GEMINI_API_KEY" \
     https://generativelanguage.googleapis.com/v1/models

Check Key Format:
Gemini: Should start with AIza...
OpenAI: Should start with sk-...
Anthropic: Should start with sk-ant-...

Frontend Issues¶

Build Failures¶

Symptoms: npm start fails or build errors

Solutions: 1. Clear Cache:

cd frontend
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Check Node Version:

node --version
# Should be 18 or higher

Environment Variables:

# Check frontend .env file
REACT_APP_API_URL=http://localhost:8000
REACT_APP_CLERK_PUBLISHABLE_KEY=your_key

Connection Issues¶

Symptoms: Frontend can't connect to backend, CORS errors

Solutions: 1. Check Backend Status:

curl http://localhost:8000/health

Verify CORS Settings:

# In backend/app.py
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Check Firewall:

# Windows
netsh advfirewall firewall show rule name="Python"

Content Generation Issues¶

SEO Analysis Not Working¶

Symptoms: SEO analysis fails or returns 422 errors

Solutions: 1. Check API Endpoints:

# Test SEO endpoint
curl -X POST http://localhost:8000/api/blog-writer/seo/analyze \
     -H "Content-Type: application/json" \
     -d '{"content": "test content"}'

Verify Request Format:

// Ensure proper request structure
const requestData = {
  content: blogContent,
  researchData: researchData,
  user_id: userId
};

Check Backend Logs:

# Look for error messages in backend console

Content Generation Failures¶

Symptoms: AI content generation fails or returns errors

Solutions: 1. Check API Quotas: - Verify API key has sufficient credits - Check rate limits and usage

Test API Connectivity:

# Test Gemini API
curl -X POST \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  https://generativelanguage.googleapis.com/v1/models/gemini-pro:generateContent

Check Request Size:
Ensure content isn't too long
Break large requests into smaller chunks

Authentication Issues¶

Clerk Authentication Problems¶

Symptoms: Login failures, authentication errors

Solutions: 1. Verify Clerk Keys:

# Check frontend .env
REACT_APP_CLERK_PUBLISHABLE_KEY=pk_test_...

Check Clerk Dashboard:
Verify domain configuration
Check user permissions
Review authentication settings
Clear Browser Cache:
```
# Clear localStorage and cookies
```

Performance Issues¶

Slow Content Generation¶

Symptoms: Long response times, timeouts

Solutions: 1. Check API Response Times:

# Monitor API performance
curl -w "@curl-format.txt" -o /dev/null -s http://localhost:8000/api/blog-writer

Optimize Request Size:
Reduce content length
Use streaming for large responses
Implement caching
Check System Resources:
```
# Monitor CPU and memory usage
top
```

Database Performance¶

Symptoms: Slow database queries, high response times

Solutions: 1. Optimize Queries:

# Add database indexes
# Use connection pooling
# Implement query caching

Check Database Size:

# Monitor database file size
ls -lh backend/alwrity.db

Debugging Tools¶

Backend Debugging¶

# Enable debug logging
import logging
logging.basicConfig(level=logging.DEBUG)

# Add debug prints
print(f"Debug: {variable_name}")

Frontend Debugging¶

// Enable React DevTools
// Add console.log statements
console.log('Debug:', data);

// Use React Developer Tools
// Check Network tab for API calls

API Testing¶

# Test API endpoints
curl -X GET http://localhost:8000/health
curl -X POST http://localhost:8000/api/blog-writer \
     -H "Content-Type: application/json" \
     -d '{"topic": "test"}'

Log Analysis¶

Backend Logs¶

# Check backend console output
# Look for error messages
# Monitor API response times

Frontend Logs¶

# Check browser console
# Monitor network requests
# Review error messages

Database Logs¶

# Check database queries
# Monitor connection issues
# Review performance metrics

Getting Help¶

Self-Service Resources¶

Documentation: Check relevant guides
GitHub Issues: Search existing issues
Community: Join discussions
FAQ: Common questions and answers

Reporting Issues¶

When reporting issues, include: 1. Error Messages: Complete error text 2. Steps to Reproduce: Detailed steps 3. Environment: OS, Python version, Node version 4. Logs: Relevant log entries 5. Screenshots: Visual error evidence

Contact Information¶

GitHub Issues: Create an issue
Documentation: Browse guides and API reference
Community: Join developer discussions

Prevention Tips¶

Regular Maintenance¶

Update Dependencies: Keep packages current
Monitor Performance: Regular performance checks
Backup Data: Regular database backups
Security Updates: Keep system secure

Best Practices¶

Environment Management: Use virtual environments
Configuration Management: Proper .env files
Error Handling: Implement proper error handling
Monitoring: Set up performance monitoring

Still having issues? Check our GitHub Issues or create a new one with detailed information about your problem.