Issue Description

AZURE_SEARCH_EXCEPTION_HANDLING_FIX

Version Implemented: 0.229.001

Issue Description

When Azure AI Search was configured but indexes didn't exist yet, the check_index_fields API endpoint was returning 500 Internal Server Error instead of a proper 404 Not Found error. The error message showed:

POST /api/admin/settings/check_index_fields 500 (Internal Server Error)
Checking user index fields: Failed to connect to Azure AI Search: () No index with the name 'simplechat-user-index' was found in the service 'simplechatexp-dev-search'.

This caused the JavaScript to handle it as a server error rather than recognizing it as a missing index that could be created.

Fixed in version: 0.227.011

Root Cause Analysis

The Azure AI Search SDK throws a ResourceNotFoundError (from azure.core.exceptions) when trying to access a non-existent index. However, the error handling was using a generic Exception catch that treated all errors the same way, resulting in 500 status codes even for expected "not found" scenarios.

Technical Details

Files Modified

• route_backend_settings.py - Added specific ResourceNotFoundError exception handling
• config.py - Version update

Before (Problematic Code)

try:
    client = get_index_client()
    current = client.get_index(expected['name'])
    # Process existing index...
except Exception as search_error:
    # Generic handling - returns 500 for all errors including "not found"
    if "not found" in str(search_error).lower():
        return jsonify({...}), 404
    else:
        return jsonify({...}), 500

After (Improved Code)

try:
    client = get_index_client()
    current = client.get_index(expected['name'])
    # Process existing index...
except ResourceNotFoundError as not_found_error:
    # Specific handling for index not found - returns 404
    return jsonify({
        'error': f'Azure AI Search index "{expected["name"]}" does not exist yet',
        'indexExists': False,
        'indexName': expected['name'],
        'needsCreation': True
    }), 404
except Exception as search_error:
    # Generic handling for other errors - still has fallback patterns
    error_str = str(search_error).lower()
    if any(phrase in error_str for phrase in [
        "not found", "does not exist", "no index with the name"
    ]):
        return jsonify({...}), 404
    else:
        return jsonify({...}), 500

Benefits

1. Proper HTTP Status Codes

• Missing indexes now return 404 Not Found instead of 500 Internal Server Error
• Enables proper client-side handling based on HTTP status

2. Specific Exception Handling

• ResourceNotFoundError is caught specifically for Azure AI Search index not found scenarios
• More reliable than string pattern matching on error messages

3. Better User Experience

• JavaScript can now properly detect missing indexes and show "Create Index" buttons
• No more misleading "Internal Server Error" messages for expected scenarios

4. Improved Logging

• Specific logging for different error types
• Better troubleshooting information for administrators

5. Fallback Protection

• Still maintains string pattern matching as a fallback for edge cases
• Robust error handling that covers multiple scenarios

Expected Behavior Changes

Before the Fix

// JavaScript console output:
POST /api/admin/settings/check_index_fields 500 (Internal Server Error)
Checking user index fields: Failed to connect to Azure AI Search: ...

// UI behavior:
- Warning message hidden due to 500 error
- No actionable button shown
- User confused about what went wrong

After the Fix

// JavaScript console output:
Checking user index fields: Azure AI Search index "simplechat-user-index" does not exist yet

// UI behavior:
- Clear message: 'Index "user" does not exist yet'
- Button shows: "Create user Index"
- User can click to create the missing index

Testing and Validation

The fix includes focused functional testing that validates:

• ✅ ResourceNotFoundError is specifically caught before generic exceptions
• ✅ Returns 404 status code for missing indexes
• ✅ Proper response structure with needsCreation: true
• ✅ Fallback error patterns still work for edge cases
• ✅ Enhanced error logging for troubleshooting
• ✅ Create index function also uses improved exception handling

Integration Notes

Azure SDK Dependencies

This fix relies on the existing import in config.py:

from azure.core.exceptions import AzureError, ResourceNotFoundError, HttpResponseError, ServiceRequestError

JavaScript Handling

The frontend JavaScript already has logic to handle 404 responses properly:

.catch(err => {
    if (err.message.includes('does not exist yet')) {
        // Show create button
        fixBtn.textContent = `Create ${type} Index`;
        fixBtn.dataset.action = 'create';
    }
});

Troubleshooting

If you still see 500 errors for missing indexes

1. Check that the Azure AI Search service endpoint is correct
2. Verify authentication credentials (managed identity or API key)
3. Check server logs for the specific exception type being thrown

If the create button doesn't appear

1. Check browser console for the actual error message
2. Verify that the 404 response includes needsCreation: true
3. Ensure JavaScript error handling is working properly

For other Azure AI Search issues

• Authentication errors will still return appropriate status codes
• Network connectivity issues will be logged separately
• Service unavailable scenarios are handled by the generic exception handler