Skip to main content

CV Extraction WebSocket Error Handling Fix

Issue Summary​

The CV extraction was failing with the error:

[AddCandidate] CV processing failed: Error: Invalid response format

When the backend returned a failed status, the error details were:

{
    "type": "pipeline_result",
    "queue": "cv_extraction_results",
    "data": {
        "id": "extract-1750858531363-dgvqknsbg",
        "status": "failed",
        "error": "Task execution error: name 'cv_parsing_task' is not defined",
        "timestamp": 0,
        "client_id": "client-1750858526300"
    }
}

Root Cause​

The issue was in the useCvExtractionWebSocket.ts hook's handleMessage function. When processing pipeline_result messages, the code was:

  1. Assuming Success Structure: It expected all pipeline_result messages to have a nested data.data structure containing the CV extraction results
  2. Not Handling Failed Status: When the pipeline returns status: "failed", the response structure is different - it has status and error directly in the data object, not nested data
  3. Poor Error Messaging: The generic "Invalid response format" error didn't help users understand what was wrong

Fix Applied​

1. Enhanced Error Detection (/lib/hooks/useCvExtractionWebSocket.ts)​

Before:

case 'pipeline_result':
  if (message.data && typeof message.data === 'object' && 'data' in message.data) {
    // Process successful response
  } else {
    const error = new Error('Invalid response format')
    // Handle as error
  }

After:

case 'pipeline_result':
  const responseData = message.data as Record<string, unknown>
  
  // Check if the response indicates failure FIRST
  if (responseData.status === 'failed') {
    const errorMessage = (responseData.error as string) || 'CV extraction failed'
    // Handle failed response with proper error message
    return
  }
  
  // Then handle successful response with nested data structure
  if (responseData && typeof responseData === 'object' && 'data' in responseData) {
    // Process successful response
  } else {
    const error = new Error('Invalid response format - missing data structure')
    // Handle invalid structure
  }

2. Improved User Error Messages (/app/company/pipeline/addCandidate/page.tsx)​

Enhanced Error Display:

  • Detects backend service errors (like cv_parsing_task not defined)
  • Shows user-friendly messages instead of technical errors
  • Provides error codes for support reference

Before:

<p className="text-sm text-red-700">{cvExtraction.error}</p>

After:

<p className="text-sm text-red-700 font-medium">CV Processing Failed</p>
<p className="text-xs text-red-600 mt-1">
  {cvExtraction.error.includes('cv_parsing_task') 
    ? 'The CV processing service is temporarily unavailable. Please try again later or contact support.'
    : cvExtraction.error}
</p>
{cvExtraction.error.includes('cv_parsing_task') && (
  <p className="text-xs text-gray-600 mt-2">
    Error code: CV_PARSER_UNAVAILABLE
  </p>
)}

3. Enhanced Logging​

Added comprehensive logging for debugging:

  • Request ID tracking
  • Detailed error context
  • Success metrics (skills count, experiences count, etc.)
  • Response structure logging for troubleshooting

Benefits​

1. Robust Error Handling​

  • ✅ Properly handles both successful and failed pipeline responses
  • ✅ Distinguishes between different error types
  • ✅ Prevents crashes from unexpected response formats

2. Better User Experience​

  • ✅ User-friendly error messages instead of technical details
  • ✅ Specific guidance for known backend issues
  • ✅ Error codes for support reference

3. Improved Debugging​

  • ✅ Detailed console logs for troubleshooting
  • ✅ Request ID tracking across the flow
  • ✅ Response structure logging
  • ✅ Success metrics reporting

Testing​

The fix handles these scenarios:

  1. Backend Service Down: Shows "CV processing service is temporarily unavailable"
  2. Task Definition Errors: Detects cv_parsing_task errors and shows appropriate message
  3. Invalid Response Structure: Shows "Invalid response format" with detailed logging
  4. Network Errors: Handled by existing WebSocket error handling
  5. Successful Extraction: Enhanced logging shows extraction metrics

Backend Issue​

The original error indicates a backend issue:

"error": "Task execution error: name 'cv_parsing_task' is not defined"

This suggests the backend pipeline service needs the cv_parsing_task to be properly defined. However, the frontend now gracefully handles this error and shows appropriate user messaging.