OptimiDoc Server Help Center
OptimiDoc Server Help Center
Breadcrumbs

Scan Workflow Errors

A scan workflow involves several independent components — the device, the OptimiDoc server, OCR processing and the destination system — and a failure in any one of them can cause a scan job to fail. This article explains how OptimiDoc's delivery fallback chain protects a scan when a destination is unavailable, then covers the most common scan workflow errors, their root causes and how to resolve them. Menu paths refer to the React web console (the primary administration interface).

How Scan Delivery Works — the Fallback Chain

Understanding the delivery order makes most "the scan did not arrive" cases easy to diagnose. When a workflow finishes capturing and processing a document, OptimiDoc delivers it in this sequence:

  1. Primary destination. The workflow's main destination is attempted first.

  2. "Deliver always" secondary destinations. Any secondary destinations marked deliver always are then attempted. These are combined (AND) with the primary result — if a deliver-always secondary fails, the delivery as a whole counts as failed and the on-error path below is triggered.

  3. On-error secondary destinations. If the steps above failed, the secondary destinations that are not marked deliver always are attempted as fallbacks. If any one of them succeeds, the scan is considered delivered.

  4. Backup to the internal OptimiDoc store. If everything above failed and the user is known, OptimiDoc redelivers the document to its own internal store, then:

    • sends the administrator a notification with the subject "OptimiDoc cannot deliver scan." naming the workflow and user, and

    • if the user has an e-mail address on file, e-mails them to say the scan could not be delivered and can be downloaded from the OptimiDoc web interface.

The practical consequence: a scan is almost never lost. If a user reports a missing scan, check the internal store and the administrator notification first — the document is very likely sitting in OptimiDoc with a "cannot deliver" notice, which tells you exactly which workflow and destination failed.

If the scan is delivered by an anonymous (unknown) user and every destination fails, the backup step is skipped — there is no user mailbox or store to fall back to. Anonymous workflows should therefore always have a reliable primary destination.

Symptoms

  • A scan job starts at the device but fails with an error on the device panel.

  • The scanned document does not arrive at the expected destination (e-mail, folder, cloud storage) but does appear in the OptimiDoc web interface with a "cannot deliver" notice.

  • OCR processing fails or produces garbled output.

  • The scan completes at the device but shows as Failed in the OptimiDoc job list.

  • Picking a subfolder while configuring a cloud/network destination shows an empty list.

Common Causes and Solutions

1. Destination Unreachable

Cause: The configured destination (network folder, SMTP server, SharePoint, cloud storage) is not reachable from the OptimiDoc server, or its authorisation has lapsed.

Diagnostic steps:

  1. Open Scanning > Destinations and edit the destination in question.

  2. Test the destination manually from the server:

    • Network folders — access the UNC path from the server (\\server\share\folder).

    • E-mail — confirm the SMTP host/port is reachable.

    • Cloud storage (OneDrive, Google Drive, SharePoint, Box, Dropbox) — confirm the OAuth authorisation is still valid.

  3. Review the server log (Diagnostics > System Logs) for destination connection errors.

Browse/subfolder errors are logged, not shown. When you browse a cloud or network destination in the UI and it fails, OptimiDoc records the failure in the server log only — a warning naming the destination and the failing step — while the UI simply shows an empty folder list. If a folder picker is unexpectedly empty, the reason is in Diagnostics > System Logs, not on screen.

Solution:

  • Network folders — verify the path and that the OptimiDoc service account has write permission.

  • E-mail — check the SMTP host, port, credentials and TLS settings under Settings > Mail Configuration.

  • Cloud storage — re-authorise the connection by editing the destination and completing the OAuth flow again. Dropbox connections use refresh tokens and survive access-token expiry, so a Dropbox destination that authorised offline access should not need routine re-authorisation; if it still fails, re-run the OAuth flow.

2. Permission Denied at Destination

Cause: The OptimiDoc service account (or the user's mapped credentials) lacks write permission at the destination.

Diagnostic steps:

  1. Identify the Windows account the OptimiDoc IIS application pool runs under.

  2. Verify that account has write access to the target folder or service.

  3. For per-user destinations (for example home folders), check the user's stored credentials.

Solution:

  • Grant the OptimiDoc service account write access to the destination.

  • For per-user destinations, ensure the user's credentials are stored and current.

3. OCR Processing Timeout or Failure

Cause: OCR is enabled in the workflow, but processing takes too long or fails — typically on very large documents or complex layouts.

How OCR timeouts actually work:

  • The built-in OptimiDoc OCR engine applies a fixed 60-minute processing limit per document. This limit is not configurable — there is no OCR-timeout setting in the UI. A document that cannot be processed within 60 minutes is effectively pathological (extreme page count or resolution).

  • The optional ABBYY OCR engine applies no such timeout.

  • OCR is CPU-intensive; throughput depends on available cores.

Diagnostic steps:

  1. Check the job in the OptimiDoc job list for OCR-specific errors.

  2. Review Diagnostics > System Logs for OCR engine errors.

  3. Scan a simple single-page document with OCR enabled to isolate the issue.

Solution:

  • For very large documents, split the original or reduce the scan resolution so OCR completes within the fixed window.

  • Ensure the server has adequate CPU and memory for OCR.

  • If OCR consistently fails on certain documents, try a different OCR language setting, or use the ABBYY engine where licensed.

4. Oversized E-mail Attachments

Cause: The scan is larger than the per-destination attachment limit configured on an e-mail destination.

How it works:

  • Each e-mail destination has an Attachment limit (MB) setting (LimitAttachment). A value of 0 disables the limit.

  • The limit is compared against the total size of the delivered files (excluding sidecar files). When the scan exceeds it, OptimiDoc does not silently drop the message — it stores the document and sends the recipient a download link instead of the attachment.

Solution:

  • Increase the attachment limit on the e-mail destination (Scanning > Destinations) if your mail system accepts larger messages.

  • Alternatively, keep the limit and rely on the download-link behaviour, or lower the scan resolution / enable more aggressive PDF compression in the workflow's PDF settings to reduce file size.

5. Disk Space Exhaustion / Old Job Buildup

Cause: The OptimiDoc server has run low on disk space, preventing scan files from being staged during processing. This is often the result of accumulated old job data.

Diagnostic steps:

  1. Check free space on the system drive and the OptimiDoc data directory.

  2. Review Diagnostics > System Logs for disk-full errors.

Solution:

  • Reclaim space by clearing old jobs: Diagnostics > Maintenance > Clear Old Jobs deletes jobs older than a chosen age (default 365 days) after a confirmation prompt. (There is no "Data Retention" settings page — job cleanup is performed from Maintenance.)

  • Held print jobs are also pruned automatically by spooler retention (configured in Settings > Print Settings), which is separate from scan handling.

  • Consider moving the OptimiDoc data directory to a larger drive and monitoring free space.

6. Invalid Scan Workflow Configuration

Cause: The scan workflow has misconfigured settings — an invalid output format, a missing or deleted destination, or a filename pattern that produces illegal characters.

Diagnostic steps:

  1. Open Scanning > Scan Workflows and edit the workflow used for the failed scan.

  2. Review the output format, resolution, colour mode, destination and filename pattern across the workflow tabs.

  3. Test with a different workflow to isolate the problem.

Solution:

  • Correct the invalid settings.

  • If the workflow references a deleted destination, assign a valid one.

  • For filename patterns, ensure the pattern resolves to characters that are legal on the target filesystem.

7. Hot Folder Not Licensed

Cause: Incoming files placed in a monitored hot folder are ignored, and the log shows HotFolder is not licensed! Cannot process incoming file ....

Explanation and solution:

  • Hot-folder input is gated by the licence: the input-source count must be greater than zero for the feature to list and process hot folders. Without it, files are left untouched and the warning is logged.

  • Verify the licence includes input sources, or contact OptimiDoc to extend it. See Licence Activation.

8. Device-Side Scan Errors

Cause: The scan fails at the device before data reaches the server — a paper jam in the ADF, a full scan memory buffer, or a device-side configuration issue.

Diagnostic steps:

  1. Check the device panel for error messages during the scan.

  2. Review the device's own system log via its embedded web server.

  3. Scan to a USB drive or the device's local box to confirm the scanner hardware works.

Solution:

  • Clear obstructions in the automatic document feeder (ADF).

  • Clear the device's local scan storage if its buffer is full.

  • Ensure the device scan settings (resolution, size limits) are compatible with the workflow.

General Diagnostic Workflow

  1. Locate the failure: device, transfer to server, processing (OCR), or delivery.

  2. Check the internal store first: a failed delivery usually leaves the scan in OptimiDoc with a "cannot deliver" notice that names the workflow and destination.

  3. Check the job list: the job status and message indicate the failure point.

  4. Review logs: Diagnostics > System Logs — remember that destination browse errors appear only here, not in the UI.

  5. Test the destination independently: write a file to it from the server.

  6. Simplify and retry: scan a single page with default settings to eliminate variables.

In Summary

OptimiDoc's delivery fallback chain — primary, then deliver-always secondaries, then on-error secondaries, then a backup to the internal store with administrator and user notifications — means a scan is rarely lost outright; the "cannot deliver" notice is your fastest diagnostic. Beyond delivery, the recurring gotchas are the fixed 60-minute OCR limit on the built-in engine (not a setting), per-destination e-mail attachment limits that switch to download links, disk cleanup that lives under Maintenance rather than a retention page, and hot-folder input that depends on the licence.

Related articles