Semantic-Org/Semantic-UI · error

JSON could not be parsed during error handling

Error message

JSON could not be parsed during error handling

What it means

This error message is defined in the API module's settings.error dictionary under the 'JSONParse' key. It is intended for situations where the response body cannot be parsed as JSON during error handling — i.e., the server returned a non-JSON response (often an HTML error page) when JSON was expected. While it is part of the error vocabulary, it is not directly invoked via module.error() in the current source version but is available for custom error handling.

Source

Thrown at src/definitions/behaviors/api.js:1130

  onComplete  : function(response, $module) {},

  // failed JSON success test
  onFailure   : function(response, $module) {},

  // server error
  onError     : function(errorMessage, $module) {},

  // request aborted
  onAbort     : function(errorMessage, $module) {},

  successTest : false,

  // errors
  error : {
    beforeSend        : 'The before send function has aborted the request',
    error             : 'There was an error with your request',
    exitConditions    : 'API Request Aborted. Exit conditions met',
    JSONParse         : 'JSON could not be parsed during error handling',
    legacyParameters  : 'You are using legacy API success callback names',
    method            : 'The method you called is not defined',
    missingAction     : 'API action used but no url was defined',
    missingSerialize  : 'jquery-serialize-object is required to add form data to an existing data object',
    missingURL        : 'No URL specified for api event',
    noReturnedValue   : 'The beforeSend callback must return a settings object, beforeSend ignored.',
    noStorage         : 'Caching responses locally requires session storage',
    parseError        : 'There was an error parsing your request',
    requiredParameter : 'Missing a required URL parameter: ',
    statusMessage     : 'Server gave an error: ',
    timeout           : 'Your request timed out'
  },

  regExp  : {
    required : /\{\$*[A-z0-9]+\}/g,
    optional : /\{\/\$*[A-z0-9]+\}/g,
  },

View on GitHub (pinned to 597843ab84)

Solutions

1. Configure the server to return JSON error responses even for error status codes.
2. Check the Content-Type header of error responses and ensure it matches application/json.
3. Use settings.successTest to validate response structure before processing.
4. Add a response interceptor that detects HTML error pages and extracts a meaningful error message.

Example fix

// before
$('.api-element').api({
  url: '/api/data'
  // server returns HTML 500 page, JSON parse fails silently
});

// after
$('.api-element').api({
  url: '/api/data',
  successTest: function(response) {
    return response && response.success !== undefined;
  },
  onError: function(errorMessage, $module, xhr) {
    var ct = xhr.getResponseHeader('content-type') || '';
    if (ct.indexOf('text/html') !== -1) {
      errorMessage = 'Server returned an HTML error page instead of JSON.';
    }
    console.error(errorMessage);
  }
});

// Pre-validate server response format before processing
$.get('/api/data').done(function(response, status, xhr) {
  var ct = xhr.getResponseHeader('content-type') || '';
  if (ct.indexOf('application/json') === -1) {
    console.error('Expected JSON, got:', ct);
    return;
  }
  try { JSON.parse(xhr.responseText); }
  catch(e) { console.error('Malformed JSON response'); }
});

// Verify a response is valid JSON
function isJsonResponse(xhr) {
  var ct = xhr.getResponseHeader('content-type') || '';
  if (ct.indexOf('application/json') === -1) return false;
  try { JSON.parse(xhr.responseText); return true; }
  catch(e) { return false; }
}

// Handle JSON parse failures in onError
$('.el').api({
  onError: function(errorMessage, $module, xhr) {
    try {
      JSON.parse(xhr.responseText);
    } catch(e) {
      console.error('Server returned non-JSON response during error handling');
    }
  }
});

When it happens

Trigger: The server returns an error response with an HTML body (e.g., a 500 error page, a reverse proxy error page) instead of JSON. The API module's response decoder (module.decode.json) fails to JSON.parse the response during error handling, leaving the raw string.

Common situations: Production servers with custom error pages (HTML) for 500/502/503 errors. Reverse proxies (nginx, HAProxy) returning HTML error pages. ASP.NET or Rails serving exception pages in development mode. Content-Type header mismatches where the server claims JSON but returns HTML.

Related errors

• There was an error parsing your request
• There was an error with your request
• Server gave an error:
• The before send function has aborted the request
• API Request Aborted. Exit conditions met

AI-assisted analysis of Semantic-Org/Semantic-UI@597843ab84 (2026-08-13). Data as JSON: /api/errors/fc4a4f6892d1d9f8. Report an issue: GitHub.