Tutorial: Handling Errors

Handling Errors

By default all errors are sent to the javascript console in the browser. However, application can override this by specifying an error-handling function in the parameters to Atalasoft.Controls.Capture.WebScanning.initialize and Atalasoft.Controls.Capture.UploadToCaptureServer.initialize.

This example shows the basic technique of specifying error-handling functions. There is a longer code example at the end of this section.

(function () {
    try {
            handlerUrl: 'WebCaptureHandler.ashx',
            onScanError: function(msg, params) { console.log(msg); },
            onUploadError: function(msg, params) { console.log(msg); }
    catch (error) {
        console.log("WebScanning initialization error: " + error.description);

Errors identification

Web Capture Service JavaScript API provides as set of typed error identifiers, so the application could distinguish and appropriate handle different kinds that errors.

All WebCapture errors are string members of Atalasoft.Controls.Capture.Errors. Each of the property of that object represents a particular error - the property name is the error identifier while the property value is the message that could be presented to user.

The value of the corresponding Atalasoft.Controls.Capture.Errors property is passed to the error-handling functions as the firs parameter. So the error handling could be based on a comparison of msg with different Atalasoft.Controls.Capture.Errors values. The second parameter of the error-handling function is the additional data having structure specific to particular error.

Errors localization

Error strings could be localized by providing params.localization values to the Atalasoft.Controls.Capture.WebScanning.initialize function. Those values will be merged with Atalasoft.Controls.Capture.Errors and thus default error messages could be overridden.

Most recent scan errors definition

  • Atalasoft.Controls.Capture.Errors.badBrowser

    Fired in: Any unsupported browser

    During: Atalasoft.Controls.Capture.WebScanning.initialize

    Cause: WebCapture Service detected that it is running in a browser it does not support. Common reasons WebCapture Service might fire this error:

    • The browser is not Internet Explorer, Firefox, Chrome, or Safary
    • The browser is one of the above, but not a supported version, for example, Internet Explorer 9.0
    • The operating system is not Windows or macOS

    How to Handle: We strongly recommend that your application display the msg parameter to the handler, or your own equivalent message. If you also display the value of the params parameter, which will be a string, it would help a technical support specialist identify the browser causing the problem. __

  • Atalasoft.Controls.Capture.Errors.noTwain Fired in: All browsers.

    During: Atalasoft.Controls.Capture.WebScanning.initialize

    Cause: Support for the TWAIN protocol itself not found on the client computer.

    Background: This error is extremely unlikely to happen on a typical end-user PC running Vista or higher, because retail editions of Windows all include a copy of the TWAIN manager. However, a user on Windows Servers 2008 R2 or higher can be missing TWAIN which will cause this error.

    How to Handle: Using scanners in Windows Server 2008 R2 with TWAIN drivers requires the installation of Desktop Experience Pack. You could just display the error string (the value of the msg parameter of the onScanError handler) or display your own message that TWAIN was not found on the computer.

  • Atalasoft.Controls.Capture.Errors.noPlugin

    Fired in:All browsers

    During: Atalasoft.Controls.Capture.WebScanning.initialize

    Cause: The required Web Scanning Service is either not installed or not running.

    How to Handle: Link to Web Scanning Service should be provided to end user to download and install service. Reinstalling service is also a legal way to restart it.
    The filename of the appropriate download is passed to your error handler as params.filename

    Alternatively user could start Web Scanning Service manually if it's already installed.

  • Atalasoft.Controls.Capture.Errors.oldPlugin

Fired in: All browsers

During: Atalasoft.Controls.Capture.WebScanning.initialize

Cause: The Web Scanning Service is installed and running but JavaScript API was updated on server to newer version.

How to Handle: Similar to handling noPlugin. User end user should download Web Scanning Service installer and update local service installation.

  • Atalasoft.Controls.Capture.Errors.oldWindowsService

    Fired in: All browsers

    During: Atalasoft.Controls.Capture.WebScanning.initialize

    Cause: The Web Scanning Service is installed as windows service and running but JavaScript API was updated on server to newer version.

    How to Handle: Most likely windows service installation indicates that Web Scanning Service is running in multiuser environment and regular user won't have enough permissions to update windows service. For such installations, shared servers should be upgraded to newer version of Web Scanning Service along with web servers by system administrators. In such case user could only be notified about error.

  • Atalasoft.Controls.Capture.Errors.licensingError

    Fired in: All browsers

    During: Asynchronously, after Atalasoft.Controls.Capture.WebScanning.initialize

    Cause: When queried, the server did not return the expected JSON licensing information in a timely fashion.

    How to Handle: If you see this during development, it suggests some server configuration problem, the handlerUrl passed to WebScanning.initialize isn't right, the server is actually off-line or not accessible, or (maybe, even) the licensing isn't right for Web Capture Service on the server. Assuming you resolve any logical problems during development, if this error occurs after deployment it almost certainly represents a typical "server not responding" error, with all the usual causes.

  • Other errors

    Other errors are possible, and additional errors may be added in future updates to Web Capture Service. We recommend that you defend against that possibility by displaying the text of the error (the msg parameter to the onScanError handler) to the user, and offering them as much flexibility as possible - for example, by linking to a troubleshooting & support page that you can revise based on experience.

    Handler: onScanError(msg, params)

The WingScan service can be initialized with a scan error handler, and that handler will potentially be called back by WingScan with one of various scanning-related errors.

Note, It is essential to a well-functioning web scanning application that you handle at least the noPlugin and oldPlugin errors. This is the standard way to deploy local service installer packages to the end user.

Sample implementation of the onScanError handler

function scanErrorHandler(msg, params)
    switch (msg) {
        case Atalasoft.Controls.Capture.Errors.badBrowser:
            prompt(msg + " <br />(" + params + ")");
        case Atalasoft.Controls.Capture.Errors.noPlugin:
            prompt("The Kofax Web Scanning plugin is not available. "+
            "Please follow any prompts to install it, or <a href='/" + params.filename + "'>Click Here</a><br />"+
            "If you are not prompted to install, the plugin may "+
            "be installed but disabled - please enable it.");
        case Atalasoft.Controls.Capture.Errors.oldPlugin:
            prompt("The Kofax Web Scanning plugin is out of date.<br />"+
            "To download and install the latest version "+
            "<a href='/" + params.filename + "'>Click Here</a>");
        case Atalasoft.Controls.Capture.Errors.noTwain:
            prompt("TWAIN is not installed on this computer.\n" +
            "Contact your system administrator.");
        case Atalasoft.Controls.Capture.Errors.oldWindowsService:
            prompt("The Kofax Web Scanning service is out of date.<br />"+
            "Contact your system administrator to update it.");

function prompt(content) {
  // present content.

Handler: onUploadError(msg, params)

Called when an error is detected during upload to the server. The msg parameter will be one of the following: