KI-Chat-Bot-Eugen/TROUBLESHOOTING.md

Eugen Bot - Troubleshooting Guide

Quick reference for diagnosing and fixing common issues with the Eugen Twitch bot.

Quick Start Diagnostic Tool

Before anything else, run the credential validator:

python test_credentials.py

This tool will:

• Test your Twitch OAuth token
• Validate your Perplexity API key
• Check model availability (sonar-pro vs sonar)
• Provide specific error messages
• Suggest exact fixes

---

Common Error Messages

1. Twitch IRC Authentication Failed

Error Output:

IRC EVENT: privnotice | Source: tmi.twitch.tv | Args: ['Login authentication failed']

Causes:

• Token is expired or invalid
• Token doesn't match the bot nickname
• Bot account is banned/suspended

Solution:

1. Verify Bot Nickname Match

   • If TWITCH_BOT_NICKNAME=Eugen, you must generate the token while logged into Twitch as Eugen
   • Token and bot nickname MUST match the same account

2. Generate New Token

   1. Go to: https://twitchtokengenerator.com
   2. Log into Twitch as the bot account
   3. Select "Bot Chat Token"
   4. Copy the full token (including oauth: prefix)
   5. Update .env file:
      TWITCH_OAUTH_TOKEN=oauth:your_new_token_here
   

3. Test the Token

   python test_credentials.py
   

2. Perplexity API 400 Bad Request

Error Output:

⚠ Unerwartete Antwort: 400

Causes:

• API key doesn't have access to sonar-pro model
• Invalid request format
• Model not available on your plan

Solution:

1. Use Model Fallback

   • The setup wizard automatically tries sonar if sonar-pro fails
   • Manually update .env:

     PERPLEXITY_MODEL=sonar
     

2. Verify API Key

   python test_credentials.py
   

3. Check API Credits

   • Go to: https://www.perplexity.ai/settings/api
   • Verify your account has credits
   • Check API key is active

3. Perplexity API 401 Unauthorized

Error Output:

✗ Perplexity API-Key ist ungültig (401 Unauthorized)

Causes:

• Invalid API key
• API key was revoked
• Typo in .env file

Solution:

1. Generate New API Key

   1. Go to: https://www.perplexity.ai/settings/api
   2. Create new API key
   3. Copy the key (starts with pplx-)
   4. Update .env:
      PERPLEXITY_API_KEY=pplx-your_new_key_here
   

2. Verify No Extra Spaces

   • Check .env file has no spaces around the = sign
   • Format: PERPLEXITY_API_KEY=pplx-abc123 (no spaces)

4. Bot Doesn't Respond in Chat

Symptoms:

• Bot connects successfully
• Bot joins channel
• But doesn't respond to mentions

Checklist:

1. Verify Bot is Mentioned Correctly

   ✓ @Eugen how are you?
   ✓ Eugen: tell me about WoW
   ✓ Eugen, what's new?
   ✗ eugen (lowercase doesn't work)
   

2. Check Debug Logs

   tail -f logs/eugen.log
   

   Look for:

   • Mention detected from {user}
   • API call to Perplexity
   • Any error messages

3. Enable Debug Mode

   DEBUG_MODE=true
   

   Restart the bot and check logs again

4. Test Credentials

   python test_credentials.py
   

5. Connection Reset by Peer

Error Output:

IRC EVENT: disconnect | Args: ['Connection reset by peer']

Causes:

• Network interruption
• Firewall blocking port 6667
• Invalid authentication (see #1)

Solution:

1. Check Firewall

   • Allow outbound connections on port 6667
   • Try temporarily disabling firewall to test

2. Verify Internet Connection

   ping irc.chat.twitch.tv
   

3. Check OAuth Token (most common cause)

   python test_credentials.py
   

6. Rate Limiting / API Quota Exceeded

Error Output:

429 Too Many Requests

Causes:

• Too many API calls in short time
• Perplexity API quota exceeded

Solution:

1. Check API Usage

   • Go to: https://www.perplexity.ai/settings/api
   • View usage and limits

2. Reduce Request Frequency

   • Consider implementing cooldowns
   • Limit responses to specific users

3. Wait and Retry

   • Wait a few minutes
   • Restart the bot

---

Diagnostic Commands

Check Configuration

cat .env

View Recent Logs

tail -n 50 logs/eugen.log

View API Debug Logs

tail -n 50 logs/api_debug.log

Test Credentials

python test_credentials.py

Run Setup Wizard Again

python setup_wizard.py

---

Getting Help

Before Asking for Help

1. Run python test_credentials.py
2. Check logs/eugen.log
3. Enable DEBUG_MODE=true and restart
4. Review this troubleshooting guide

Information to Include

When reporting issues, include:

• Error messages from logs
• Output of python test_credentials.py
• Contents of .env (REDACT secrets!)
• Python version: python --version
• OS: Windows/Linux/Mac

Resources

• GitHub Issues: https://github.com/Kenearos/KI-Chat-Bot-Eugen/issues
• Twitch Token Generator: https://twitchtokengenerator.com
• Perplexity API: https://www.perplexity.ai/settings/api

---

Quick Reference

File Locations

• Configuration: .env
• Main log: logs/eugen.log
• API debug: logs/api_debug.log
• Conversations: data/conversations/

Required Credentials

• Twitch OAuth Token (starts with oauth:)
• Twitch Bot Nickname (must match token account)
• Twitch Channel (starts with #)
• Perplexity API Key (starts with pplx-)

Testing Tools

• python setup_wizard.py - Interactive setup
• python test_credentials.py - Validate credentials
• python chatbot.py - Run the bot