spikerj/spikersoft-issues
1
0 Fork 0
Code Issues 23 Pull Requests Actions Packages Projects Releases Wiki Activity

# [Bug] Client-side OCR Fails to Decode MRZ Lines in Profile Configuration #1111

New Issue
Closed
opened 2026-08-27 14:34:53 +00:00 by enjin2310 · 2 comments
enjin2310 commented 2026-08-27 14:34:53 +00:00
Copy link
Copy source

Summary

The passport OCR feature fails to decode MRZ (Machine Readable Zone) lines during profile configuration, displaying a NetworkError message and preventing data extraction.

Issue Description

When attempting to upload or process a passport image in the Profile Configuration section, the system displays the error message:

“Client-side OCR failed: NetworkError: A network error occurred.”
The failure occurs immediately after uploading the image, and no MRZ data is extracted or displayed. The issue appears to be related to the client-side OCR network request or connectivity handling.

Environment

Property Value
Application SpikerSoft Learn
Module Profile Configuration
Feature Passport Information (OCR Extraction)
Environment Production
Browser Firefox
Operating System Windows 11
Version v2026.08.27b
Device Desktop

Preconditions

User must be logged in and have access to the Passport Information section in the profile configuration page.

Steps to Reproduce

  1. Log in to the SpikerSoft platform.
  2. Navigate to Profile > Configuration.
  3. In the Passport Information section, upload a passport image (e.g., passport-image.jpeg).
  4. Wait for the OCR extraction process to start.

Expected Result

The OCR process should decode the MRZ lines from the passport image and populate the corresponding fields automatically.

Actual Result

The OCR process fails with a NetworkError, and no data is extracted. The error message appears both in the red alert banner and as a popup notification.

Evidence

  • Screenshot shows the error message:
    “Unable to decode — Client-side OCR failed: NetworkError: A network error occurred.”
  • The passport image (passport-image.jpeg) is uploaded successfully, but the extraction process does not proceed.
  • The same error message appears twice: once in the banner and once in a modal dialog.

Impact

  • Users cannot automatically extract passport data.
  • Manual data entry is required, increasing the risk of errors.
  • The OCR feature becomes unusable in production environments.

Frequency

Always

Reproducibility

100%

Severity

High

Notes

The issue may be caused by:

  • A failed network request to the OCR processing endpoint.
  • Incorrect client-side handling of offline or timeout conditions.
  • Missing fallback logic for local OCR decoding.

It is recommended to:

  • Verify the OCR API endpoint connectivity.
  • Implement retry logic or offline fallback for client-side OCR.
  • Log detailed error traces for debugging network failures.
## Summary The passport OCR feature fails to decode MRZ (Machine Readable Zone) lines during profile configuration, displaying a **NetworkError** message and preventing data extraction. ## Issue Description When attempting to upload or process a passport image in the **Profile Configuration** section, the system displays the error message: > “Client-side OCR failed: NetworkError: A network error occurred.” The failure occurs immediately after uploading the image, and no MRZ data is extracted or displayed. The issue appears to be related to the client-side OCR network request or connectivity handling. ## Environment | Property | Value | |-----------|--------| | Application | SpikerSoft Learn | | Module | Profile Configuration | | Feature | Passport Information (OCR Extraction) | | Environment | Production | | Browser | Firefox | | Operating System | Windows 11 | | Version | v2026.08.27b | | Device | Desktop | ## Preconditions User must be logged in and have access to the **Passport Information** section in the profile configuration page. ## Steps to Reproduce 1. Log in to the SpikerSoft platform. 2. Navigate to **Profile > Configuration**. 3. In the **Passport Information** section, upload a passport image (e.g., `passport-image.jpeg`). 4. Wait for the OCR extraction process to start. ## Expected Result The OCR process should decode the MRZ lines from the passport image and populate the corresponding fields automatically. ## Actual Result The OCR process fails with a **NetworkError**, and no data is extracted. The error message appears both in the red alert banner and as a popup notification. ## Evidence - Screenshot shows the error message: “Unable to decode — Client-side OCR failed: NetworkError: A network error occurred.” - The passport image (`passport-image.jpeg`) is uploaded successfully, but the extraction process does not proceed. - The same error message appears twice: once in the banner and once in a modal dialog. ## Impact - Users cannot automatically extract passport data. - Manual data entry is required, increasing the risk of errors. - The OCR feature becomes unusable in production environments. ## Frequency Always ## Reproducibility 100% ## Severity High ## Notes The issue may be caused by: - A failed network request to the OCR processing endpoint. - Incorrect client-side handling of offline or timeout conditions. - Missing fallback logic for local OCR decoding. It is recommended to: - Verify the OCR API endpoint connectivity. - Implement retry logic or offline fallback for client-side OCR. - Log detailed error traces for debugging network failures.
Screenshot 2026-08-27 103402.png
190 KiB
Screenshot 2026-08-27 103402.png
spikerj commented 2026-08-30 16:07:30 +00:00
Owner
Copy link
Copy source

Confirmed and fixed — and your instinct that it was network-related was reasonable, but the truth is sneakier: it is a path bug wearing a network error's clothes.

The OCR engine was configured with document-relative asset paths (./assets/mrz-ocr/…). A relative URL resolves against the current page, so from Profile > Configuration the browser went looking for the OCR worker, the WASM core and the MRZ language model under /profile/assets/… instead of /assets/….

Measured on production:

/assets/mrz-ocr/tesseract/worker.min.js          -> 200  (111 KB)
/profile/assets/mrz-ocr/tesseract/worker.min.js -> 404

Tesseract reports a failed fetch as NetworkError: A network error occurred, which is exactly why the message blamed the network and why this survived so long.

Nice side effect of your report: every nested route was affected, so the passport scan in the employment application dialog was broken in the same way — only a root-level page would ever have worked. Both are fixed by the same change.

Fix: spikerj/spikersoft-angular#890 (paths made root-absolute, with a unit test pinning the contract so it cannot silently regress).

Will close once it merges and deploys.

Confirmed and fixed — and your instinct that it was network-related was reasonable, but the truth is sneakier: it is a **path** bug wearing a network error's clothes. The OCR engine was configured with document-relative asset paths (`./assets/mrz-ocr/…`). A relative URL resolves against the current page, so from **Profile > Configuration** the browser went looking for the OCR worker, the WASM core and the MRZ language model under `/profile/assets/…` instead of `/assets/…`. Measured on production: ``` /assets/mrz-ocr/tesseract/worker.min.js -> 200 (111 KB) /profile/assets/mrz-ocr/tesseract/worker.min.js -> 404 ``` Tesseract reports a failed fetch as `NetworkError: A network error occurred`, which is exactly why the message blamed the network and why this survived so long. Nice side effect of your report: **every nested route** was affected, so the passport scan in the employment application dialog was broken in the same way — only a root-level page would ever have worked. Both are fixed by the same change. Fix: spikerj/spikersoft-angular#890 (paths made root-absolute, with a unit test pinning the contract so it cannot silently regress). Will close once it merges and deploys.
spikerj commented 2026-08-30 23:54:23 +00:00
Owner
Copy link
Copy source

Fixed and merged — closing.

The OCR worker assets were requested on paths relative to the current route, so they 404d on any nested URL. Now root-absolute (spikerj/spikersoft-angular#890).

The change is on master and deployed. Please re-test when you get a chance; if you still see it, reopen this issue rather than filing a new one so the history stays together.

Fixed and merged — closing. The OCR worker assets were requested on paths relative to the current route, so they 404d on any nested URL. Now root-absolute (spikerj/spikersoft-angular#890). The change is on `master` and deployed. Please re-test when you get a chance; if you still see it, reopen this issue rather than filing a new one so the history stays together.
Sign in to join this conversation.
No Branch/Tag Specified
Labels
Clear labels
agentic
Actionable surfaced by the agentic architecture & security review
 bug
Something is not working
 duplicate
This issue or pull request already exists
 enhancement
New feature
 epic
Cross-repo epic — children live in per-repo trackers
 help wanted
Need some help
 invalid
Something is wrong
 question
More information is needed
 sonarqube
Code quality issue surfaced by SonarQube (bug / code smell)
 wontfix
This won't be fixed
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
spikerj (Joseph Spiker)
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: spikerj/spikersoft-issues#1111