TROUBLESHOOTING_QUICK_REFERENCE.md

TRIQA Hugging Face Demo - Quick Troubleshooting Reference

🚨 Common Errors & Quick Fixes

1. Short Description Too Long

Error: "short_description" length must be less than or equal to 60 characters long

Quick Fix:

# In README.md
short_description: TRIQA-IQA  # 9 characters

2. Missing timm Module

Error: ModuleNotFoundError: No module named 'timm'

Quick Fix:

# Add to requirements.txt
timm>=0.6.0

3. Model Files Not Found

Error: FileNotFoundError: [Errno 2] No such file or directory: 'feature_models/...'

Quick Fix:

1. Download from Box: https://utexas.box.com/s/8aw6axc2lofouja65uc726lca8b1cduf
2. Create directories: feature_models/ and Regression_Models/
3. Upload model files to correct locations

4. Build Failures

Error: Various build errors

Quick Fix:

1. Check space logs
2. Verify all dependencies in requirements.txt
3. Test locally: python app.py

📋 Essential Files Checklist

Required Files:

• app.py - Main application
• README.md - Space description
• requirements.txt - Dependencies
• package.json - Node.js config
• convnext_original.py - Model architecture
• convnext_finetune.py - Model architecture
• sample_image/ - Sample images

Model Files (Download from Box):

• feature_models/convnext_tiny_22k_224.pth (170MB)
• feature_models/triqa_quality_aware.pth (107MB)
• Regression_Models/KonIQ_scaler.save
• Regression_Models/KonIQ_TRIQA.save (111MB)

🔧 Quick Commands

Upload Files:

# Python CLI
python upload_to_space.py

# Git method
git clone https://huggingface.co/spaces/your-username/triqa-iqa
cd triqa-iqa
cp ../huggingface_demo/* .
git add . && git commit -m "Add TRIQA demo" && git push

Test Locally:

# Test file structure
python test_demo.py

# Test app
python app.py

Update Single File:

python -c "from huggingface_hub import HfApi; api = HfApi(); api.upload_file(path_or_fileobj='filename', path_in_repo='filename', repo_id='S-Rajesh/triqa-iqa', repo_type='space')"

📊 Requirements.txt Template

gradio>=4.0.0
torch>=1.8.0
torchvision>=0.9.0
timm>=0.6.0
pillow>=8.0.0
numpy>=1.19.0
scikit-learn>=0.24.0

🎯 README.md Metadata Template

---
title: TRIQA Image Quality Assessment
emoji: 🖼️
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.0.0
app_file: app.py
pinned: false
license: mit
short_description: TRIQA-IQA
---

🚀 Space URL Format

https://huggingface.co/spaces/USERNAME/SPACE-NAME

Example: https://huggingface.co/spaces/S-Rajesh/triqa-iqa

⚡ Quick Debug Steps

1. Check build logs in your space
2. Verify file paths are correct
3. Test locally before uploading
4. Check dependencies in requirements.txt
5. Verify model files are uploaded

📞 Quick Links

• Space: https://huggingface.co/spaces/S-Rajesh/triqa-iqa
• Box Download: https://utexas.box.com/s/8aw6axc2lofouja65uc726lca8b1cduf
• GitHub: https://github.com/rajeshsureddi/triqa
• Paper: https://arxiv.org/pdf/2507.12687

✅ Success Indicators

• Space builds without errors
• Demo interface loads
• Sample images display
• Quality prediction works
• Paper links are accessible

---

Remember: Most issues are solved by checking the build logs and ensuring all dependencies are properly listed in requirements.txt! 🎯