GRADIO_API_CONFLICT_DIAGNOSIS.md

Gradio API Endpoint Conflict Diagnosis Guide

Overview

This document helps diagnose and resolve conflicts with Gradio API endpoints in the Research AI Assistant application.

Current Setup

• Framework: Gradio (Python), NOT Express/Node.js
• Port: 7860 (configurable via GRADIO_PORT env var)
• Host: 0.0.0.0 (all interfaces)
• API Enabled: Yes (show_api=True)
• Deployment: Hugging Face Spaces / Local

Common Conflict Scenarios

1. Port Conflicts

Symptoms:

• Error: "Address already in use"
• Application fails to start
• Port binding errors in logs

Diagnosis:

# Check if port 7860 is already in use
# Windows
netstat -ano | findstr :7860

# Linux/Mac
lsof -i :7860
# or
netstat -tulpn | grep 7860

Solutions:

Option A: Change Gradio Port

# In app.py, modify demo.launch():
demo.launch(
    server_name="0.0.0.0",
    server_port=7861,  # Use different port
    show_api=True
)

Option B: Use Environment Variable

# Set before running
export GRADIO_PORT=7861
python app.py

Option C: Kill Conflicting Process

# Windows (find PID from netstat)
taskkill /PID <PID> /F

# Linux/Mac
kill -9 <PID>

---

2. Multiple Gradio Instances Running

Symptoms:

• Multiple instances competing for the same port
• Unpredictable endpoint routing
• Some endpoints work, others don't

Diagnosis: Check for multiple Python processes:

# Windows
tasklist | findstr python

# Linux/Mac
ps aux | grep python | grep app.py

Solution: Ensure only one instance is running:

# Kill all Python processes (use with caution!)
# Windows
taskkill /IM python.exe /F

# Linux/Mac
pkill -f app.py

---

3. API Endpoint Routing Conflicts

Symptoms:

• 404 errors on /api/* endpoints
• Endpoints return wrong responses
• API documentation not accessible at /docs

Diagnosis:

Check 1: Verify API is Enabled

# Add to app.py after demo creation
print(f"API Open: {demo.config.api_open}")
print(f"Show API: {demo.config.show_api}")

Check 2: Verify Endpoint Registration Look for this in logs:

✓ API endpoint '/api/safe_gpu_chat_handler' registered with api_name
✓ API handler function initialized: True

Check 3: Test Endpoint Directly

# Check if API docs are accessible
curl http://localhost:7860/docs

# Test endpoint
curl -X POST http://localhost:7860/api/safe_gpu_chat_handler \
  -H "Content-Type: application/json" \
  -d '{"data": ["test", [], "Admin_J", ""]}'

Solutions:

Ensure API is Explicitly Enabled:

# In app.py (line 2109-2116)
demo.launch(
    server_name="0.0.0.0",
    server_port=7860,
    share=False,
    show_api=True,  # ✅ This must be True
    # ... other settings
)

Verify Handler Function is Set:

# Check that _api_chat_handler_fn is not None
# This is set at lines 1899-1900 or 2002-2003 in app.py

---

4. CORS Issues (Cross-Origin Resource Sharing)

Symptoms:

• Browser console shows CORS errors
• API calls from external domains fail
• "Access-Control-Allow-Origin" errors

Solutions:

Option A: Enable CORS in Gradio Launch

demo.launch(
    server_name="0.0.0.0",
    server_port=7860,
    show_api=True,
    # Add CORS configuration
    allowed_paths=["*"],  # Allow all paths (or specify)
    # Note: Gradio handles CORS automatically when show_api=True
)

Option B: Use Gradio's Share Feature (for external access)

demo.launch(
    server_name="0.0.0.0",
    server_port=7860,
    share=True,  # Creates public Gradio link
    show_api=True
)

Option C: Add CORS Headers Manually (if needed)

# If using FastAPI/Flask alongside Gradio, add CORS middleware
# But this app doesn't use FastAPI/Flask, so this shouldn't be needed

---

5. Hugging Face Spaces Deployment Conflicts

Symptoms:

• Works locally but not on HF Spaces
• Port conflicts in container
• API endpoints unavailable

Solutions:

Check HF Spaces Configuration:

1. Ensure Dockerfile.hf exposes correct port:

   EXPOSE 7860
   

2. Verify app.py is the main entry point (check README.md for sdk: gradio)

3. Check HF Spaces logs for startup errors:

   • Go to your Space settings
   • View Logs tab
   • Look for "LAUNCHING GRADIO APP" message

Common HF Spaces Issues:

• Port 7860 is required (cannot be changed on HF Spaces)
• server_name="0.0.0.0" is correct
• share=True is automatically disabled on HF Spaces (they provide their own public URL)
• The code automatically detects HF Spaces and disables share to prevent warnings

---

6. API Endpoint Not Found (404)

Symptoms:

• /api/safe_gpu_chat_handler returns 404
• Endpoint not listed in /docs

Diagnosis Checklist:

1. ✅ Handler Function Initialized?

   # Check logs for:
   # "✓ API handler function initialized: True"
   

2. ✅ api_name Parameter Set?

   # In app.py line 845:
   api_message.submit(
       fn=api_chat_handler,
       inputs=[...],
       outputs=[...],
       api_name="safe_gpu_chat_handler"  # ✅ Must be present
   )
   

3. ✅ show_api=True in launch()?

   demo.launch(show_api=True)  # ✅ Must be True
   

4. ✅ App Restarted After Changes?

   • Gradio requires restart to register new endpoints

Solution:

# Verify in app.py:
# 1. Handler function exists (lines 804-836)
# 2. api_name is set (line 845)
# 3. show_api=True in launch (line 2113)
# 4. Restart the application

---

7. Gradio vs. FastAPI/Flask Conflicts (Not Applicable Here)

Note: This application uses only Gradio - there is no FastAPI or Flask server running.

If you're trying to add FastAPI alongside:

# DON'T do this - Gradio handles routing
from fastapi import FastAPI
app = FastAPI()  # This would conflict!

Gradio's internal server handles all routing. You don't need Express, FastAPI, or Flask.

---

Diagnostic Commands

Complete Health Check

# 1. Check if app is running
curl http://localhost:7860/

# 2. Check API documentation
curl http://localhost:7860/docs

# 3. Check API info endpoint
curl http://localhost:7860/api_info

# 4. Test chat endpoint
curl -X POST http://localhost:7860/api/safe_gpu_chat_handler \
  -H "Content-Type: application/json" \
  -d '{"data": ["Hello", [], "Admin_J", ""]}'

# 5. Check logs for errors
# Windows
type app.log | findstr ERROR

# Linux/Mac
grep ERROR app.log

Verify Endpoint Registration

# Use the provided verification script
python verify_api_endpoint.py http://localhost:7860

---

Configuration Reference

Current Launch Configuration (app.py:2109-2116)

# Automatically detects HF Spaces and adjusts share setting
use_share = not SPACES_GPU_AVAILABLE  # False on HF Spaces, True locally
demo.launch(
    server_name="0.0.0.0",        # Accept connections from all interfaces
    server_port=7860,              # Default Gradio port
    share=use_share,               # Auto: True locally, False on HF Spaces
    show_api=True,                 # Enable API endpoints
    allowed_paths=[],              # Security: don't serve files
    blocked_paths=["/tmp", "/var", "/etc", "/home"]  # Block sensitive paths
)

Environment Variables

# Port configuration (optional - defaults to 7860)
export GRADIO_PORT=7860

# Host configuration (optional - defaults to 0.0.0.0)
export GRADIO_HOST=0.0.0.0

---

Troubleshooting Checklist

Use this checklist when experiencing issues:

• Port 7860 is not in use by another process
• Only one instance of app.py is running
• show_api=True is set in demo.launch()
• api_name parameter is set on the submit event
• Handler function (_api_chat_handler_fn) is not None
• Application logs show "API endpoint registered" message
• /docs endpoint is accessible
• /api_info endpoint returns JSON
• Application was restarted after code changes
• No CORS errors in browser console (if accessing from browser)
• HF Spaces configuration is correct (if deploying to Spaces)

---

Quick Fixes

Fix 1: Port Conflict

# Change port in app.py line 2111:
server_port=7861

Fix 2: API Not Enabled

# Ensure in app.py line 2113:
show_api=True  # Not False!

Fix 3: Handler Not Set

# Check lines 1899-1900 or 2002-2003:
# _api_chat_handler_fn must be assigned

Fix 4: Restart Required

# Stop and restart the application
# Endpoints only register on startup

---

Getting Help

If issues persist:

1. Check Logs: Review app.log for error messages
2. Run Verification Script: python verify_api_endpoint.py
3. Test Manually: Use curl commands above
4. Check HF Spaces Logs: If deploying to Hugging Face

---

Summary

This is a Gradio-only application. There are no Express, FastAPI, or Flask servers. All routing is handled by Gradio's internal server. Common conflicts are:

1. Port conflicts → Change port or kill conflicting process
2. API not enabled → Set show_api=True
3. Handler not initialized → Check initialization code
4. Multiple instances → Ensure only one is running
5. CORS issues → Gradio handles automatically, but check if accessing from external domain

If you're experiencing specific errors, share:

• The exact error message
• Where you're running (local, HF Spaces, etc.)
• The endpoint that's failing
• Log output from app startup