# Issue Description

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

- Skill: `tools-only/issue-description-4` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/issue-description-4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/issue-description-4/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/issue-description-4

---

# 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)
```python
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)
```python
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
// 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
// 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`:
```python
from azure.core.exceptions import AzureError, ResourceNotFoundError, HttpResponseError, ServiceRequestError
```

### JavaScript Handling
The frontend JavaScript already has logic to handle 404 responses properly:
```javascript
.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