Troubleshooting
Troubleshooting Guide
Common Issues
Bot Won’t Start
Symptoms
- No response to commands
- “Bot is not ready” errors
- Python crashes on startup
Solutions
- Check Python version:
python --version # Should be 3.10+ - Verify dependencies:
pip install -r requirements.txt --upgrade - Check environment variables:
cat .env # Should contain DISCORD_TOKEN and OPENAI_API_KEY - Validate bot token:
- Go to Discord Developer Portal
- Regenerate token if needed
- Update .env file
OpenAI Errors
“Invalid API Key”
Solution:
1. Check .env file has correct key
2. Verify key at platform.openai.com
3. Check for extra spaces/quotes
4. Regenerate key if needed
“Rate limit exceeded”
Solution:
1. Reduce max_tokens settings
2. Add cooldowns to commands
3. Check OpenAI usage dashboard
4. Upgrade OpenAI plan if needed
“Cannot import OpenAI”
Solution:
pip install --upgrade openai
# If using old version:
pip install openai==0.28.0
Discord Errors
“Missing Permissions”
Solution:
1. Re-invite bot with correct permissions
2. Check role hierarchy
3. Verify channel permissions
4. Use !botinfo to check status
“Cannot create thread”
Solution:
1. Check bot has thread permissions
2. Verify not at thread limit
3. Check channel type supports threads
4. Try in different channel
“Buttons don’t show or don’t work”
Solution:
1. Ensure the bot has permission to send messages and use external emojis in the channel
2. Check that interactions aren't blocked by channel permissions
3. Verify there are no errors about timeouts in logs (RPS and Hi‑Lo use view timeouts)
4. For Hi‑Lo, the Cash Out button is enabled only after completing round 1
Database Issues
“Database is locked”
Solution:
1. Restart the bot
2. Check file permissions:
chmod 644 *.db
3. Remove .db-journal files
4. Backup and recreate database
“No such table”
Solution:
1. Delete the .db file
2. Restart bot (recreates tables)
3. Check init_db functions
“Casino chips not granting on first play”
Solution:
1. Ensure Casino feature is enabled (!enable casino)
2. The welcome bonus grants only once per user per guild; check `games_stats.db` → `casino_ledger` for `game='welcome'`
3. Try a different casino command (slots/hilo/roulette) to trigger first play
4. Verify the bot has write permissions on games_stats.db
“Faucet says already claimed”
Solution:
1. Faucet is once every 24 hours (rolling window)
2. Check `last_faucet` column in `casino_chips` for the user
3. Wait until 24h has passed or test with a different account
“RPS stats not updating”
Solution:
1. Confirm games feature is enabled (!features)
2. Check that games_stats.db exists and is writable
3. Look for "Error recording RPS result" in logs
4. Use !rpsstats to verify values per server
Configuration Problems
“Config not updating”
Solution:
1. Use !reloadconfig command
2. Check JSON syntax:
python -m json.tool myconfig.json
3. Verify file permissions
4. Check for typos in keys
“Command not found”
Solution:
1. Check required_role setting
2. Verify user has permission
3. Use !help to see available commands
4. Check if module loaded correctly
5. Remember: new or changed commands require a bot restart to register with Discord
Assets
“Roulette help image doesn’t show”
Solution:
1. Confirm file exists at image-assets/roulette-table.png
2. Bot needs permission to attach files in the channel
3. If missing, the command falls back to text-only help
Error Messages
ChatGPT Errors
| Error | Meaning | Solution |
|---|---|---|
| “Sorry, I couldn’t generate a response” | API call failed | Check API key and credits |
| “Token limit exceeded” | Response too long | Reduce max_tokens |
| “Invalid prompt” | Prompt formatting error | Check prompt templates |
Fishing Game Errors
| Error | Meaning | Solution |
|---|---|---|
| “No fish assets found” | Missing images | Add images to FishingGameAssets/ |
| “You need to wait X seconds” | Cooldown active | Wait or adjust cooldown |
| “Could not add fish” | Config error | Check fish name matches image |
Thread Errors
| Error | Meaning | Solution |
|---|---|---|
| “Failed to create thread” | Discord API error | Check permissions and limits |
| “Thread not found” | Thread deleted | Create new thread |
| “Not a chat thread” | Wrong thread type | Use in bot-created threads |
Debugging Steps
1. Enable Logging
Add to main.py:
import logging
logging.basicConfig(level=logging.INFO)
2. Check Console Output
Look for:
- Startup messages
- Error tracebacks
- API responses
- Database queries
3. Test Individual Components
# Test OpenAI
python -c "from openai import OpenAI; print('OK')"
# Test Discord.py
python -c "import discord; print(discord.__version__)"
# Test database
python -c "import sqlite3; print('OK')"
4. Verify File Structure
discord-bot-for-fun/
├── main.py
├── chatgpt.py
├── games.py
├── fishing_game.py
├── .env
├── myconfig.json
├── my_fishing_game_config.json
├── FishingGameAssets/
│ └── (fish images)
├── conversations.db
├── chatgpt_stats.db
├── fishing_game.db
└── games_stats.db
Performance Issues
Bot is Slow
- Check token limits - Reduce for faster responses
- Monitor API calls - Enable token usage display
- Database optimization - Vacuum databases periodically
- Reduce thread retention - Lower retention period
High Memory Usage
- Clear old threads - Use cleanup task
- Limit conversation history - Already capped at 20
- Restart periodically - Schedule restarts
- Monitor with:
!botinfo
Getting Help
Information to Provide
When asking for help, include:
- Error message (full traceback)
- Bot version (!botinfo output)
- Python version
- Recent changes
- Config settings (without tokens!)
Where to Get Help
- GitHub Issues: Bug reports
- GitHub Discussions: Questions
- Discord Support: If available
- Documentation: Check all guides
Emergency Recovery
If nothing works:
- Backup data:
cp *.db backup/ cp my*.json backup/ - Fresh install:
git pull pip install -r requirements.txt --upgrade - Reset configs:
cp config.json myconfig.json cp fishing_game_config.json my_fishing_game_config.json - Restart bot:
python main.py
Preventive Measures
Regular Maintenance
- Weekly backups of databases
- Monitor API usage and costs
- Update dependencies monthly
- Review error logs regularly
- Test commands after changes
Best Practices
- Use version control for configs
- Document custom changes
- Test in dev server first
- Keep dependencies updated
- Monitor Discord/OpenAI status
Generated from repository docs. Last build: 2025-09-12 11:03 UTC