5.16.2

Handling Errors

Fine Uploader has a wealth of ways to respond to error messages. By default, Fine Uploader assumes an error when the server response does not have a key of success set to true. If any error is thrown, then the onError callback will be invoked.

Debugging Errors

Sometimes errors are not intended, or unexpected. Fine Uploader provides the debug option which will make the plugin spit out logging messages to the browser's developer tools console.

To enable debug mode, set the debug option of Fine Uploader to true and open the developer console in your browser. Interact with Fine Uploader and notice that it is logging specifically what is happening. These messages can be crucial in determining why something is not working as expected.

Handling Errors

Handling error messages and errors can take place inside of the onError callback. onError is triggered whenever Fine Uploader encounters an error. The text to be displayed in the case of an error is passed in as the errorReason parameter.

The following code snippet shows how one might display a custom alert on the event of an error.

var uploader = new qq.FineUploader({
    /* other required config options left out for brevity */

    callbacks: {
        onError: function(id, name, errorReason, xhrOrXdr) {
            alert(qq.format("Error on file number {} - {}.  Reason: {}", id, name, errorReason));
        }
    }
});

The Error Response Property

By default, if Fine Uploader does not receive a successful server response, it will look for the error property of the response body and will pass that value to the onError callback.

If the server indicates failure in the response, but does not include an error property and the response status indicates failure, then the defaultResponseError property will be used as the error message.

var uploader = new qq.FineUploader({
    /* other required config options left out for brevity */

    text: {
        defaultResponseError: 'An unknown upload error occurred.'
    }
});

Changing Error Messages

The messages property in the core Fine Uploader options provides a handful of properties one can override to display custom error messages.

var uploader = new qq.FineUploader({
    /* other required config options left out for brevity */

    messages: {
        typeError: '{file} has an invalid extension. Valid extension(s): {extensions}.'
        // other messages can go here as well ...
    }
});

Error Messages

Error messages include primitive String interpolation that allows integrators to inject variable data into error messages. For example, the typeError message could be modified:

messages: {
    typeError: 'Invalid extension detected in file, {file}.'
}

The filename of the file which the error was thrown on will be injected instead of the "{file}" String.

Modifying the Text for Failed Uploads

The failedUploadTextDisplay option defines properties used for displaying text when an upload fails.

var uploader = new qq.FineUploader({
    /* other required config options left out for brevity */

    // These are all the DEFAULT values...
    failedUploadTextDisplay: {
        mode: 'default',
        responseProperty: 'error',
    }
});

The mode property has three settings, each of which determine how failed upload errors are displayed.

  • 'default' will display the failUploadText defined in the text option properties next to each item.
  • 'none' will not display any text next to a failed item.
  • 'custom' will display an error response text from the server next to each failed item).
    • 'custom' mode will use the provided responseProperty (which defaults to 'error') as its text