05 - Troubleshooting Guide¶

Comprehensive troubleshooting guide for common issues, error messages, and solutions when running the API.

🔍 Quick Diagnosis¶

First Steps for Any Issue¶

Check server status:
```
curl http://localhost:8000/health
```

Verify environment:

source bin/activate
python -c "from internal.config.settings import settings; settings.validate_required_settings()"

Check logs:

tail -f server.log  # if running in background
# or check terminal output if running in foreground

🚨 Server Startup Issues¶

Issue: `ModuleNotFoundError: No module named 'internal'`¶

Cause: Virtual environment not activated or dependencies not installed.

Solution:

# Activate virtual environment
source bin/activate

# Reinstall dependencies
pip install -r requirements.txt

# Verify Python path
python -c "import sys; print(sys.path)"

Issue: `Port 8000 already in use`¶

Cause: Another process is using port 8000.

Solution:

# Find what's using the port
sudo lsof -i :8000

# Kill the process (replace PID with actual process ID)
sudo kill -9 PID

# Or use a different port
uvicorn main:app --port 8001

# Or kill all Python processes (be careful!)
pkill -f python

Issue: `Permission denied` when starting server¶

Cause: File permission issues.

Solution:

# Fix permissions
chmod +x main.py
chmod -R 755 /home/supradmin/apiv2

# Check ownership
ls -la main.py
sudo chown -R $USER:$USER /home/supradmin/apiv2

Issue: `FileNotFoundError: [Errno 2] No such file or directory: '.env'`¶

Cause: Environment file missing or in wrong location.

Solution:

# Check current directory
pwd

# Look for .env file
ls -la .env

# Create .env if missing
cp .env.example .env  # if example exists
# or create manually following 02-environment-setup.md

🔑 Environment and API Key Issues¶

Issue: `Missing required environment variables`¶

Error Message: ValueError: Missing required environment variables: GEMINI_API, ELEVENLABS_API_KEY

Solution:

# Check .env file exists and has correct variables
cat .env

# Verify environment loading
python -c "
from dotenv import load_dotenv
import os
load_dotenv()
print('GEMINI_API:', bool(os.getenv('GEMINI_API')))
print('ELEVENLABS_API_KEY:', bool(os.getenv('ELEVENLABS_API_KEY')))
"

# Edit .env file to add missing variables
nano .env

Issue: `google.auth.exceptions.DefaultCredentialsError`¶

Error Message: Could not automatically determine credentials

Solution:

# Check service account file exists
ls -la sa/supradmin-0c4280905b78.json

# Set environment variable manually
export GOOGLE_APPLICATION_CREDENTIALS="/home/supradmin/apiv2/sa/supradmin-0c4280905b78.json"

# Test authentication
python -c "
from google.cloud import storage
client = storage.Client()
print('GCS authentication successful!')
"

# If file is missing, follow 02-environment-setup.md to recreate

Issue: `Invalid API key` for Gemini¶

Error Message: 400 API key not valid

Solution:

# Test API key manually
python -c "
import os
import google.generativeai as genai
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv('GEMINI_API')
print(f'API Key starts with: {api_key[:10] if api_key else \"None\"}...')

try:
    genai.configure(api_key=api_key)
    model = genai.GenerativeModel('gemini-2.0-flash')
    response = model.generate_content('Hello')
    print('✅ Gemini API working!')
except Exception as e:
    print(f'❌ Gemini API error: {e}')
"

# Get new API key from https://makersuite.google.com/app/apikey

Issue: ElevenLabs API errors¶

Error Message: 401 Unauthorized or Invalid API key

Solution:

# Test ElevenLabs API key
curl -X GET "https://api.elevenlabs.io/v1/voices" \
  -H "xi-api-key: YOUR_ELEVENLABS_KEY"

# Check current key
python -c "
import os
from dotenv import load_dotenv
load_dotenv()
key = os.getenv('ELEVENLABS_API_KEY')
print(f'ElevenLabs key starts with: {key[:10] if key else \"None\"}...')
"

# Get new key from https://elevenlabs.io/app/settings

🎬 FFmpeg and Video Issues¶

Issue: `FileNotFoundError: [Errno 2] No such file or directory: 'ffmpeg'`¶

Cause: FFmpeg not installed or not in PATH.

Solution:

# Check if FFmpeg is installed
ffmpeg -version

# Install FFmpeg (Ubuntu/Debian)
sudo apt update
sudo apt install ffmpeg

# Install FFmpeg (CentOS/RHEL)
sudo yum install ffmpeg

# Install FFmpeg (macOS)
brew install ffmpeg

# Test Python FFmpeg integration
python -c "
import ffmpeg
print('✅ FFmpeg-python working!')
import moviepy.config as mp_config
print('✅ MoviePy config loaded!')
"

Issue: Video generation fails with codec errors¶

Error Message: Codec 'libx264' not found or similar

Solution:

# Check available codecs
ffmpeg -codecs | grep x264

# Install additional codecs (Ubuntu)
sudo apt install ubuntu-restricted-extras

# Install x264 codec
sudo apt install libx264-dev

# Try alternative codec in video generation
# Edit internal/services/video_service.py to use different codec

Issue: Video files not found for generation¶

Error Message: Audio file not found or Image file not found

Solution:

# Check directory structure
ls -la audio/ images/

# For title "Product Name", files should be named:
# audio/Product_Name.mp3
# images/Product_Name.jpg (or Product_Name-1.jpg, Product_Name-2.jpg, etc.)

# Verify file naming
python -c "
import re
title = 'Product Name'
safe_title = re.sub(r'[^a-zA-Z0-9]', '_', title)
print(f'Safe title: {safe_title}')
print(f'Expected audio: audio/{safe_title}.mp3')
print(f'Expected image: images/{safe_title}.jpg')
"

📺 YouTube API Issues¶

Issue: YouTube authorization fails¶

Error Message: invalid_client or unauthorized_client

Solution:

# Check YouTube credentials
cat sa/oauth.json

# Verify client ID and secret in .env
grep YOUTUBE .env

# Get fresh OAuth2 credentials:
# 1. Go to Google Cloud Console
# 2. APIs & Services > Credentials
# 3. Create new OAuth2 client ID
# 4. Download JSON and save as sa/oauth.json

Issue: YouTube upload fails with `quotaExceeded`¶

Error Message: The request cannot be completed because you have exceeded your quota

Solution:

# YouTube API has daily quotas
# Wait until quota resets (usually next day)
# Or request quota increase from Google Cloud Console

# Check current quota usage:
# Google Cloud Console > APIs & Services > YouTube Data API v3 > Quotas

Issue: `youtube_credentials.pickle` file issues¶

Error Message: FileNotFoundError or authentication errors

Solution:

# Remove old credentials
rm -f youtube_credentials.pickle sa/youtube_token.pickle

# Re-authenticate
curl http://localhost:8000/youtube-auth-url
# Follow the URL and complete authorization process

🌐 Network and Connectivity Issues¶

Issue: API requests timeout or fail¶

Symptoms: Long delays, connection refused, timeout errors

Solution:

# Check internet connectivity
ping google.com

# Test specific API endpoints
curl -v https://api.elevenlabs.io/v1/voices
curl -v https://generativelanguage.googleapis.com/v1beta/models

# Check firewall settings
sudo ufw status
sudo iptables -L

# Check DNS resolution
nslookup api.elevenlabs.io
nslookup generativelanguage.googleapis.com

Issue: Google Cloud Storage upload fails¶

Error Message: 403 Forbidden or 401 Unauthorized

Solution:

# Test GCS authentication
python -c "
from google.cloud import storage
client = storage.Client()
buckets = list(client.list_buckets())
print(f'Accessible buckets: {len(buckets)}')
"

# Check bucket permissions
gsutil ls gs://merchant-ary
gsutil iam get gs://merchant-ary

# Create bucket if doesn't exist
gsutil mb gs://your-bucket-name

💾 Storage and File Issues¶

Issue: `No space left on device`¶

Solution:

# Check disk space
df -h

# Clean up generated files
rm -f videos_output/*.mp4
rm -f tts/*.mp3
rm -f audio/*.mp3  # Be careful with this one

# Clean up Python cache
find . -name "__pycache__" -type d -exec rm -rf {} +
find . -name "*.pyc" -delete

Issue: File permission errors¶

Error Message: Permission denied when accessing files

Solution:

# Fix directory permissions
chmod -R 755 audio images videos_output tts sa

# Fix file permissions
chmod 644 audio/*.mp3 images/*.jpg images/*.png
chmod 600 sa/*.json .env

# Check ownership
ls -la audio/ images/
sudo chown -R $USER:$USER /home/supradmin/apiv2

🔄 Performance Issues¶

Issue: API responses are very slow¶

Symptoms: Requests taking >30 seconds, timeouts

Diagnosis:

# Check CPU and memory usage
top
htop  # if installed

# Monitor API performance
time curl -X POST "http://localhost:8000/summarize" \
  -H "Content-Type: application/json" \
  -d '{"text": "test text"}'

# Check for background processes
ps aux | grep python

Solutions:

# Restart the server
pkill -f "python main.py"
python main.py

# Clear temporary files
rm -rf __pycache__/
rm -f *.pyc

# Monitor resource usage
watch -n 1 'ps aux | grep python | grep -v grep'

Issue: Memory usage grows over time¶

Symptoms: Server becomes unresponsive after many requests

Solution:

# Restart server periodically
# Set up a cron job for automatic restart:
crontab -e
# Add: 0 4 * * * pkill -f "python main.py" && cd /home/supradmin/apiv2 && python main.py &

# Use production server with workers
pip install gunicorn
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

🧪 Testing and Debugging¶

Debug Mode Setup¶

Enable detailed logging:
```
export LOG_LEVEL=DEBUG
python main.py
```

Test individual components:

# Test text summarizer
python -c "
from internal.services.text_summarizer import TextSummarizer
summarizer = TextSummarizer()
result = summarizer.summarize('Test text for debugging')
print(result)
"

# Test TTS service
python -c "
from internal.services.tts_service import TTSService
tts = TTSService()
# Test method calls here
"

Manual API testing:

# Test with detailed curl output
curl -v -X POST "http://localhost:8000/health"

# Test with different content types
curl -X POST "http://localhost:8000/summarize" \
  -H "Content-Type: application/json" \
  -d '{"text": "debug test"}' \
  -w "\n%{http_code}\n%{time_total}\n"

Common Debug Commands¶

# Check all environment variables
env | grep -E "(GEMINI|ELEVENLABS|YOUTUBE|GOOGLE)"

# Verify file structure
find . -name "*.py" | head -10
find . -name "*.json" | head -5

# Test Python imports
python -c "
try:
    from internal.config.settings import settings
    print('✅ Settings import successful')
    from internal.services.text_summarizer import TextSummarizer
    print('✅ TextSummarizer import successful')
    from internal.services.tts_service import TTSService
    print('✅ TTSService import successful')
except Exception as e:
    print(f'❌ Import error: {e}')
"

# Check service status
python -c "
from internal.config.settings import settings
print(f'Gemini API configured: {bool(settings.GEMINI_API_KEY)}')
print(f'ElevenLabs API configured: {bool(settings.ELEVENLABS_API_KEY)}')
print(f'YouTube configured: {bool(settings.YOUTUBE_CLIENT_ID)}')
"

📞 When to Get Help¶

Issues requiring system admin help:¶

Network connectivity problems
Firewall configuration
System-level permission issues
Hardware resource constraints

Issues requiring API provider help:¶

Google Cloud quota limits
YouTube API restrictions
ElevenLabs service outages
Billing and payment issues

Self-solvable issues:¶

Environment variable configuration
File permission problems
Python dependency conflicts
Basic API usage questions

🔧 Emergency Recovery¶

Complete System Reset¶

If everything is broken, follow these steps:

Backup current state:

cp .env .env.backup
cp -r sa/ sa_backup/

Clean installation:

# Deactivate and remove virtual environment
deactivate
rm -rf bin/ lib/ include/ pyvenv.cfg

# Recreate virtual environment
python3 -m venv .
source bin/activate
pip install -r requirements.txt

Restore configuration:

cp .env.backup .env
cp -r sa_backup/ sa/

Test basic functionality:

python -c "from internal.config.settings import settings; settings.validate_required_settings()"
python main.py

Rollback to Working State¶

If you have a backup:

# Stop current server
pkill -f "python main.py"

# Restore from backup
cp backup/.env .env
cp -r backup/sa/ sa/
cp backup/main.py main.py  # if modified

# Restart server
python main.py

📋 Troubleshooting Checklist¶

Before asking for help, verify:

🎯 Next Steps¶

For technical details and architecture: - 06-architecture.md - Technical architecture and code organization

05 - Troubleshooting Guide¶

🔍 Quick Diagnosis¶

First Steps for Any Issue¶

🚨 Server Startup Issues¶

Issue: ModuleNotFoundError: No module named 'internal'¶

Issue: Port 8000 already in use¶

Issue: Permission denied when starting server¶

Issue: FileNotFoundError: [Errno 2] No such file or directory: '.env'¶

🔑 Environment and API Key Issues¶

Issue: Missing required environment variables¶

Issue: google.auth.exceptions.DefaultCredentialsError¶

Issue: Invalid API key for Gemini¶

Issue: ElevenLabs API errors¶

🎬 FFmpeg and Video Issues¶

Issue: FileNotFoundError: [Errno 2] No such file or directory: 'ffmpeg'¶

Issue: Video generation fails with codec errors¶

Issue: Video files not found for generation¶

📺 YouTube API Issues¶

Issue: YouTube authorization fails¶

Issue: YouTube upload fails with quotaExceeded¶

Issue: youtube_credentials.pickle file issues¶

🌐 Network and Connectivity Issues¶

Issue: API requests timeout or fail¶

Issue: Google Cloud Storage upload fails¶

💾 Storage and File Issues¶

Issue: No space left on device¶

Issue: File permission errors¶

🔄 Performance Issues¶

Issue: API responses are very slow¶

Issue: Memory usage grows over time¶

🧪 Testing and Debugging¶

Debug Mode Setup¶

Common Debug Commands¶

📞 When to Get Help¶

Issues requiring system admin help:¶

Issues requiring API provider help:¶

Self-solvable issues:¶

🔧 Emergency Recovery¶

Complete System Reset¶

Rollback to Working State¶

📋 Troubleshooting Checklist¶

🎯 Next Steps¶

Issue: `ModuleNotFoundError: No module named 'internal'`¶

Issue: `Port 8000 already in use`¶

Issue: `Permission denied` when starting server¶

Issue: `FileNotFoundError: [Errno 2] No such file or directory: '.env'`¶

Issue: `Missing required environment variables`¶

Issue: `google.auth.exceptions.DefaultCredentialsError`¶

Issue: `Invalid API key` for Gemini¶

Issue: `FileNotFoundError: [Errno 2] No such file or directory: 'ffmpeg'`¶

Issue: YouTube upload fails with `quotaExceeded`¶

Issue: `youtube_credentials.pickle` file issues¶

Issue: `No space left on device`¶