Complete guide for diagnosing and resolving common TutorBot issues.
This guide covers common problems, their causes, and step-by-step solutions for the TutorBot application.
Before diving into specific issues, run through this checklist:
Error: TypeError: object of type 'NoneType' has no len() at line 2102
Cause: Webhook content can be None, causing length check to fail
Solution: Fixed in main.py line 2102
# Before (causing error):
message_content = data.get("content", "")[:50] + "..." if len(data.get("content", "")) > 50 else data.get("content", "")
# After (fixed):
content = data.get("content", "")
message_content = content[:50] + "..." if content and len(content) > 50 else content or ""
Prevention: Always check for None values before string operations
# Check container status
docker-compose ps
# View startup logs
docker-compose logs tutorbot
# Check port usage
sudo netstat -tulpn | grep :5000
# Verify environment variables
docker-compose exec tutorbot env
Port Already in Use:
# Kill process using port 5000
sudo lsof -ti:5000 | xargs kill -9
# Or use different port
docker-compose up -p 5001:5000
Missing Environment Variables:
# Export environment variables
source scripts/dev/export_env.sh
# Restart container
docker-compose restart tutorbot
Python Dependencies:
# Rebuild container
docker-compose build --no-cache
# Check requirements.txt
docker-compose exec tutorbot pip list
# Test Chatwoot API connection
curl -H "api_access_token: $CW_ADMIN_TOKEN" \
"$CW_URL/api/v1/accounts/$CW_ACC_ID/contacts"
# Check webhook configuration
curl -X POST https://your-domain.com/cw \
-H "Content-Type: application/json" \
-d '{"test": "webhook"}'
# Verify HMAC signature
# Check Chatwoot webhook logs
Invalid API Token:
# Regenerate API token in Chatwoot
# Update .env file with new token
source scripts/dev/export_env.sh
docker-compose restart tutorbot
Webhook Not Receiving Events:
# Check webhook URL in Chatwoot
# Verify HMAC secret matches
# Test webhook endpoint accessibility
HMAC Verification Failures:
# Regenerate HMAC secret
# Update both Chatwoot and .env
# Restart application
# Test OpenAI API connection
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
"https://api.openai.com/v1/models"
# Check API key validity
python3 -c "import openai; openai.api_key='$OPENAI_API_KEY'; print(openai.Model.list())"
Invalid API Key:
# Generate new OpenAI API key
# Update .env file
source scripts/dev/export_env.sh
docker-compose restart tutorbot
Rate Limit Exceeded:
# Check usage in OpenAI dashboard
# Implement rate limiting in code
# Consider upgrading API plan
Model Not Available:
# Check model availability
# Update OPENAI_MODEL in .env
# Restart application
# Test Stripe webhook endpoint
curl -X POST https://your-domain.com/webhook/payments \
-H "Content-Type: application/json" \
-d '{"test": "webhook"}'
# Check Stripe dashboard for webhook failures
# Verify webhook secret
Invalid Webhook Secret:
# Regenerate webhook secret in Stripe
# Update STRIPE_WEBHOOK_SECRET in .env
# Restart application
Price ID Not Found:
# Verify price IDs in Stripe dashboard
# Update price IDs in .env file
# Test payment link generation
Webhook Not Receiving Events:
# Check webhook endpoint URL
# Verify SSL certificate
# Test endpoint accessibility
# Test Google Calendar API
python3 -c "
import json
from google.oauth2 import service_account
from googleapiclient.discovery import build
SCOPES = ['https://www.googleapis.com/auth/calendar']
SERVICE_ACCOUNT_FILE = '$GCAL_SERVICE_ACCOUNT_JSON'
credentials = service_account.Credentials.from_service_account_file(
SERVICE_ACCOUNT_FILE, scopes=SCOPES)
service = build('calendar', 'v3', credentials=credentials)
events = service.events().list(calendarId='$GCAL_CALENDAR_ID').execute()
print('Calendar access OK')
"
Service Account Issues:
# Regenerate service account key
# Update JSON file in config/
# Verify calendar sharing
Calendar Not Shared:
# Share calendar with service account email
# Check calendar permissions
# Verify calendar ID
API Quota Exceeded:
# Check Google Cloud Console
# Implement rate limiting
# Consider quota increase
# Enable debug mode
./scripts/debug_toggle.sh on
# Check debug status
./scripts/debug_toggle.sh status
# View debug logs
docker-compose logs -f tutorbot
Debug mode provides:
# Real-time logs
docker-compose logs -f tutorbot
# Recent logs
docker-compose logs --tail=100 tutorbot
# Logs with timestamps
docker-compose logs -t tutorbot
# Container resource usage
docker stats
# Disk space
df -h
# Memory usage
free -h
# Check OpenAI usage
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
"https://api.openai.com/v1/usage"
# Check Stripe webhook events
# (Check Stripe dashboard)
# Test external connectivity
docker-compose exec tutorbot ping google.com
# Test DNS resolution
docker-compose exec tutorbot nslookup api.openai.com
# Check firewall rules
sudo ufw status
# Fix file permissions
chmod -R 755 .
chmod 600 .env
# Check ownership
ls -la
# Fix ownership if needed
sudo chown -R $USER:$USER .
# Check database connectivity
docker-compose exec tutorbot python -c "
import requests
print('Database connection test')
"
# Verify database schema
# (If using external database)
# Restart application
docker-compose restart tutorbot
# Full restart with rebuild
docker-compose down
docker-compose up --build -d
# Clean restart
docker-compose down -v
docker-compose up --build -d
# Restore from backup
cp .env.backup.$(date +%Y%m%d) .env
# Reset to defaults
cp env_example.txt .env
# Reconfigure environment
source scripts/dev/export_env.sh
# Backup current data
docker-compose exec tutorbot tar -czf backup.tar.gz /app/data
# Restore from backup
docker-compose exec tutorbot tar -xzf backup.tar.gz -C /app
When seeking help, include:
Last Updated: August 2025
Version: 2.0
Maintainer: Stephen Adei