# Troubleshooting Guide

## Common Issues and Solutions

### 🔄 HuggingFace API Update (November 2025)

**Important:** HuggingFace has updated their Inference API endpoint.

**If you see 404 errors:**
- ✅ Make sure you're using the latest version of `llm_backend.py`
- ✅ The new endpoint is: `https://router.huggingface.co/hf-inference/`
- ✅ Old endpoint (`api-inference.huggingface.co`) is deprecated

**Already updated:** This version uses the new Inference Providers API automatically.

---

### ❌ "LLM backend not configured" Error

**Symptom:** App shows warning banner, features don't work

**Cause:** No LLM provider credentials found

**Solutions:**

#### On HuggingFace Spaces

**Option 1: Make Space Public (Easiest)**
1. Go to your Space Settings
2. Change Visibility: Private → **Public**
3. Refresh/Restart the Space
4. HF_TOKEN will automatically be available

**Option 2: Add Token Manually (for Private Spaces)**
1. Get your token: https://huggingface.co/settings/tokens
2. Create token with "Read" permission (if you don't have one)
3. Go to Space Settings → Variables
4. Add variable:
   - Name: `HUGGINGFACE_API_KEY`
   - Value: your_token_here
5. Restart the Space

**Option 3: Use Premium Provider**
1. Get API key from OpenAI or Anthropic
2. Go to Space Settings → Variables
3. Add:
   - `LLM_PROVIDER=openai`
   - `OPENAI_API_KEY=sk-your-key`
4. Restart Space

#### Running Locally

**Check your environment:**
```bash
python check_env.py
```

**Set credentials:**
```bash
# For OpenAI (recommended)
export OPENAI_API_KEY="sk-your-key-here"

# OR for Anthropic
export ANTHROPIC_API_KEY="your-key-here"

# OR for HuggingFace
export HUGGINGFACE_API_KEY="your-token-here"

# Then run
python app.py
```

---

### ⏱️ Generation Takes Too Long

**Symptom:** Waiting 30+ seconds for survey generation

**Cause:** HuggingFace free tier can be slow, especially during high usage

**Solutions:**

1. **Be patient on first request** - Models "cold start", can take 60+ seconds
2. **Try again** - You might hit a faster server
3. **Simplify requests:**
   - Use shorter outlines (2-3 sentences)
   - Request fewer questions (5-10)
   - Translate one language at a time
4. **Upgrade to paid provider:**
   ```bash
   LLM_PROVIDER=openai
   OPENAI_API_KEY=sk-your-key
   ```
   Much faster, costs ~$0.01-0.05 per survey

---

### 🔴 "AttributeError: 'NoneType' object has no attribute..."

**Symptom:** App crashes on startup

**Cause:** Interface trying to use backend before it's initialized

**Solution:** Update to latest version - this has been fixed

**If still happening:**
1. Check `app.py` has the latest code
2. Verify `get_language_choices()` doesn't depend on `survey_trans` instance
3. Make sure all functions check `if survey_gen:` before using it

---

### 📊 Analysis Returns Empty/Poor Results

**Symptom:** Analysis doesn't find themes or gives generic insights

**Causes & Solutions:**

1. **Too few responses:**
   - Need 10-20+ responses for meaningful analysis
   - Add more sample data

2. **Low-quality model:**
   - Free HF models may struggle with complex analysis
   - Upgrade to OpenAI GPT-4 or Claude for better analysis

3. **Responses too short:**
   - Analysis works best with detailed, paragraph-length responses
   - Encourage respondents to elaborate

4. **Wrong format:**
   - Make sure responses are properly formatted JSON
   - Use the "Load Example" button to see correct format

---

### 🌍 Translation Failed

**Symptom:** Translation returns error or garbled text

**Causes & Solutions:**

1. **No survey generated:**
   - Generate a survey first before translating
   - Or upload a valid survey JSON

2. **Model limitations:**
   - Free HF models may struggle with some languages
   - Use OpenAI or Anthropic for better translations
   - Try more common languages (Spanish, French) first

3. **Rate limit:**
   - Wait a few minutes
   - Translate fewer languages at once

---

### 💾 Downloads Don't Work

**Symptom:** Can't download survey/analysis files

**Cause:** Browser/Gradio issues

**Solutions:**

1. **Check browser console** for errors (F12)
2. **Try different browser** (Chrome, Firefox)
3. **Copy-paste data** manually from the output box
4. **Check Gradio version** - update to latest:
   ```bash
   pip install --upgrade gradio
   ```

---

### 🔒 Private Space Issues

**Symptom:** Works in public Space but not private

**Cause:** HF_TOKEN not available in private Spaces

**Solution:**

Add token manually:
1. https://huggingface.co/settings/tokens
2. Copy token with "Read" permission
3. Space Settings → Variables → Add `HUGGINGFACE_API_KEY`
4. Restart

---

### 🚫 Rate Limit Errors

**Symptom:** "Rate limit exceeded" or 429 errors

**HuggingFace Free Tier:**
- Wait 5-10 minutes
- Reduce request frequency
- Upgrade to Pro: https://huggingface.co/pricing

**OpenAI:**
- Check usage: https://platform.openai.com/usage
- Add credits or wait for reset
- Use GPT-3.5 instead of GPT-4 (cheaper)

**Anthropic:**
- Check console: https://console.anthropic.com
- Add credits or upgrade plan

---

### 📱 Mobile/Responsive Issues

**Symptom:** UI doesn't work well on mobile

**Cause:** Gradio has some mobile limitations

**Solutions:**
- Use landscape orientation
- Use tablet or desktop for best experience
- Some features may be limited on mobile

---

## Debugging Steps

### 1. Check Environment
```bash
python check_env.py
```

Look for:
- ✅ At least one API key is SET
- ✅ All dependencies installed
- ✅ Provider will be detected

### 2. Check Logs

**On HuggingFace Spaces:**
- Go to "Logs" tab
- Look for "=== LLM Backend Initialization ==="
- Check which credentials are found

**Running locally:**
- Check terminal output
- Look for initialization messages
- Check for errors/warnings

### 3. Test Backend
```bash
python test_hf_backend.py
```

Should show:
- ✅ Backend initialized
- ✅ Generation successful
- ✅ ALL TESTS PASSED

### 4. Start Simple

If issues persist:
1. **Test with OpenAI first** (most reliable)
2. **Use example data** from the UI
3. **Try one feature at a time** (generation only)
4. **Check network connectivity**

---

## Getting Help

### Before Asking for Help

1. ✅ Run `python check_env.py`
2. ✅ Check logs for error messages
3. ✅ Try with example data
4. ✅ Update to latest code
5. ✅ Read this troubleshooting guide

### Where to Get Help

1. **Check documentation:**
   - `README.md` - Overview
   - `USAGE_GUIDE.md` - How to use
   - `DEPLOYMENT.md` - Setup instructions
   - `QUICK_START_HF_SPACES.md` - Fast deployment

2. **Common resources:**
   - Gradio docs: https://gradio.app/docs
   - HuggingFace docs: https://huggingface.co/docs
   - OpenAI docs: https://platform.openai.com/docs

3. **Report issues:**
   - Include output from `check_env.py`
   - Include relevant logs
   - Describe what you tried

---

## Performance Tips

### For Best Results

**Model Selection:**
- **Best Quality:** OpenAI GPT-4 or Anthropic Claude 3.5 Sonnet
- **Best Value:** OpenAI GPT-4o-mini
- **Free:** HuggingFace (slower, lower quality)

**Request Optimization:**
- Keep outlines concise (2-4 sentences)
- Request 10-15 questions (not 25)
- Translate common languages first
- Provide 20+ responses for analysis

**Cost Control:**
- Use GPT-4o-mini instead of GPT-4 ($0.15 vs $5 per 1M tokens)
- Cache common surveys
- Batch operations when possible
- Monitor usage dashboards

---

## Emergency Fixes

### App Won't Start At All

```bash
# 1. Clean install
rm -rf venv
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt

# 2. Check environment
python check_env.py

# 3. Try with minimal config
export OPENAI_API_KEY="sk-your-key"
python app.py
```

### App Starts But Nothing Works

```bash
# 1. Verify backend
python test_hf_backend.py

# 2. Check imports
python -c "from llm_backend import LLMBackend; print('OK')"
python -c "from survey_generator import SurveyGenerator; print('OK')"

# 3. Test manually
python
>>> from llm_backend import LLMBackend, LLMProvider
>>> backend = LLMBackend(provider=LLMProvider.OPENAI)
>>> backend.generate([{"role": "user", "content": "Hello"}], max_tokens=10)
```

---

**Still stuck?** Make sure you're using the latest version of all files and have followed the setup instructions carefully.