Add comprehensive credential validation and troubleshooting tools
This commit adds robust diagnostic tools to help users identify and fix authentication issues with Twitch OAuth and Perplexity API. New Features: - test_credentials.py: Comprehensive credential validator with detailed diagnostics - Tests Twitch OAuth token with IRC authentication - Validates Perplexity API key and model access - Provides specific error messages and actionable fixes - Automatically tests fallback models (sonar-pro → sonar) - TROUBLESHOOTING.md: Complete troubleshooting guide - Common error messages and solutions - Step-by-step diagnostic procedures - Quick reference for file locations and commands Improvements to setup_wizard.py: - Enhanced Twitch token validation with detailed error messages - Added Perplexity model fallback (sonar-pro → sonar) - Better error handling with specific solutions - Recommends working model if primary model unavailable Documentation Updates: - README.md: Added credential testing section with examples - CLAUDE.md: Updated with new tools and testing procedures - Comprehensive troubleshooting section in README This addresses the common authentication failures users encounter during initial setup and provides clear paths to resolution.
This commit is contained in:
Claude
parent
f45f73e335
commit
ddedd4867c
5 changed files with 807 additions and 53 deletions
279
TROUBLESHOOTING.md
Normal file
279
TROUBLESHOOTING.md
Normal file
|
|
@ -0,0 +1,279 @@
|
|||
# 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:
|
||||
|
||||
```bash
|
||||
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**
|
||||
```bash
|
||||
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**
|
||||
```bash
|
||||
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**
|
||||
```bash
|
||||
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**
|
||||
```bash
|
||||
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**
|
||||
```bash
|
||||
ping irc.chat.twitch.tv
|
||||
```
|
||||
|
||||
3. **Check OAuth Token** (most common cause)
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
cat .env
|
||||
```
|
||||
|
||||
### View Recent Logs
|
||||
```bash
|
||||
tail -n 50 logs/eugen.log
|
||||
```
|
||||
|
||||
### View API Debug Logs
|
||||
```bash
|
||||
tail -n 50 logs/api_debug.log
|
||||
```
|
||||
|
||||
### Test Credentials
|
||||
```bash
|
||||
python test_credentials.py
|
||||
```
|
||||
|
||||
### Run Setup Wizard Again
|
||||
```bash
|
||||
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
|
||||
Loading…
Add table
Add a link
Reference in a new issue