As document digitization continues to grow across industries, software developers rely heavily on a reliable document scanning SDK to integrate scanning functionalities into their web or desktop applications. However, like any complex technology, developers may occasionally encounter unexpected issues during integration, deployment, or usage. 

 

Let’s address the most frequent problems users face when using a document scanning SDK such as Dynamic Web TWAIN and learn step-by-step resolutions for each scenario.  

 

Troubleshooting Common Issues in Document Scanner SDK 

Identifying the root causes of the common issues and applying the recommended solutions can help developers maintain smooth document scanning operations. Some of the common issues in document scanning that you can face are: 

 

1. General Failure Error 

When attempting to scan an image, the SDK may throw an error message stating “General failure” through the ErrorString property. This issue typically occurs when the scanner source was not properly disabled after a previous session or if the device is temporarily unavailable.  

 

To resolve this, it’s important to ensure that all previous connections to the scanner are fully closed. You should use the methods CloseSource() and CloseSourceManager() before calling SelectSource() again. This resets the scanner source and prepares it for a fresh scanning session. 

 

2. Server Connection Issues 

When uploading scanned images to the web server, the operation may fail with a message indicating that a connection with the server could not be established. This issue typically arises when the document scanning SDK is unable to reach the server, often due to incorrect port settings or because the server is currently unavailable.  

 

To address this, first verify that the HTTP port defined in your application code matches the port configured on your web server. You can explicitly set the correct port using the HTTPPort property. Additionally, ensure that the server is accessible by pinging its IP address or hostname from a client machine to confirm network connectivity. 

 

3. HTTP Request Error 

When uploading images via HTTP PUT requests, an error may be returned by the document scanning SDK. This issue generally arises due to a lack of ‘write‘ permissions on the server or due to server configuration restrictions. For instance, Apache Tomcat, by default, disallows PUT operations unless explicitly enabled. To resolve this, start by ensuring that the web server directory has write permissions enabled. 

 

If you are using IIS, open the IIS Manager, navigate to Web Sites and locate your site. Right-click the target folder, select Properties, go to the Directory tab, and check the “Write” option to grant the necessary permission. 

 

If your application is hosted on Tomcat, navigate to the {Tomcat installation directory}/conf/web.xml file. Locate the DefaultServlet configuration and modify the readonly property by setting its value to false. This change allows the HTTP PUT operation to function as expected within the SDK. 

 

4. HTTP Process Error 

When using HTTPUpload or similar methods in a document scanning SDK, image uploads may fail, triggering an error message. This issue can stem from several common causes. One possibility is that the server directory lacks the necessary write permissions. Another potential cause is an incorrect or malformed action page URL, which prevents the server from properly handling the upload request. Additionally, if the wrong port is specified for HTTP uploads or if the image size exceeds the server’s configured upload limit, the process will fail. 

 

To resolve this, ensure that write permissions are granted to relevant user groups, such as “Authenticated Users.” Use the HTTPPostResponseString property to inspect the HTTP response and identify the specific reason for the failure. Also, confirm that the correct port is being used by setting it through the HTTPPort property. If the issue relates to file size, review and update the server-side settings to allow larger uploads. This comprehensive approach can help ensure smoother image upload operations via the SDK. 

 

5. Sequence Error in TWAIN Operations 

A sequence error in TWAIN operations typically occurs when image acquisition from the scanner fails due to commands being executed out of the required order. This issue is often related to improper handling of the TWAIN protocol, which follows a specific sequence for operations. 

 

To resolve this, it is important to follow the correct acquisition flow. Always start by calling OpenSource() before attempting to access any properties such as PixelType. Additionally, make sure to use the appropriate TWAIN lifecycle methods in the correct order to avoid unexpected behavior. Adhering to the required sequence ensures smooth and reliable communication between the scanning application and the device. 

 

6. Abnormal Server Disconnection 

An abnormal server disconnection error can occur when uploading images, often accompanied by the message: “The connection with the server was terminated abnormally.” This issue generally stems from either an unavailable server connection or when the image size exceeds the server’s defined maximum transferable data limit. 

 

To resolve this, first verify that the server is available by using a ping command from the client machine. Also, ensure that the HTTP port specified in your application matches the one configured on the server. While the default is port 80, you can define other ports using the HTTPPort property.  

 

Additionally, if the image size is causing the issue, adjust the server’s maximum transferable size accordingly. For ASP.NET, modify the maxRequestLength value in the Web.config file. For PHP environments, update the upload_max_filesize and post_max_size values in the php.ini configuration file. These changes help prevent disconnection issues during large image uploads. 

 

7. JavaScript Reference Errors 

JavaScript reference errors may occur during web-based scanning operations, typically showing the message: “Uncaught ReferenceError – DVS is not defined.” This error is caused when Dynamic Web TWAIN resources are not loaded correctly. The most common reasons include incorrect path settings or missing essential files from the SDK. 

 

To resolve this issue, start by verifying that the path to the Resources folder is correctly defined in your application. Next, check if the viewer.js file exists under the {ResourcesPath}/src directory. It's also important to ensure that all necessary files were properly deployed during the SDK installation. Correctly setting the paths and confirming that all files are present will eliminate the reference error and allow the web scanner to function properly. 

 

8. Product Key-Related Errors 

Several common licensing issues may also arise during SDK deployment. These include: 


  • One such issue is the use of an unsupported feature or platform, where the error message typically states, “The current product key does not support XXX...”. This occurs when you're attempting to use a feature not included in your license or deploying on an unsupported platform or browser. The resolution is to confirm that your license key covers all the necessary features and platforms. Contact the SDK provider if needed. 
  • Another issue involves unsupported operating systems for embedded devices. You might see a message saying, “The current product key does not support the current OS for embed device...”. This means the SDK is being used on an OS not covered in the license. In such cases, ensure your license includes support for the embedded OS you intend to use. 
  • A different problem could be an empty or invalid product key, indicated by the message: “The current product key is empty or invalid...”. This usually means that the configuration is missing a valid license key. To fix it, reconfigure the SDK settings and input the correct product key. 
  • You may also encounter a missing core license issue, where the message reads, “The current product key is missing the core license...”. This happens when only add-ons are licensed and the base SDK components are not included. Ensure that your license includes the necessary core SDK features to avoid this error. 
  • Lastly, a license version mismatch can occur, leading to the message: “The current product key is invalid because it’s generated with the licenses of a different major version...”. This problem arises when the license used does not match the SDK’s major version. To resolve this, use a license that corresponds exactly with the SDK version you are running. 

 

Final Thoughts 

Integrating a document scanning SDK into your application can dramatically streamline paper-to-digital workflows. However, successful deployment and maintenance require a good understanding of how the SDK interacts with both hardware and server environments. 

 

By understanding and applying the troubleshooting strategies above, developers can quickly address errors, maintain operational efficiency, and deliver a smooth scanning experience to end-users. 

 

If persistent issues remain unresolved, always refer to your SDK documentation or contact the vendor’s support team for detailed assistance.