TROUBLESHOOTING.md

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:

python check_env.py

Set credentials:

# 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:

   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:

   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

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

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

# 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

# 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.