Spaces:
Sleeping
Sleeping
| # 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. | |