Troubleshooting

Common troubleshooting scenarios across platforms and their step-by-step solutions.

1. Model Files & Assets Not Found

Symptom

Runtime exception during initialization: Failed to initialize RustO with config, Model asset not found, or FileNotFoundException.

Root Cause

The engine cannot locate det.rten, rec.rten, or dict.txt in the active working directory or app bundle.

Resolution

• Rust / CLI / C FFI: Verify that relative paths are relative to the current working directory, or pass absolute paths (e.g. /usr/share/models/det.rten).
• .NET / C#: Ensure you installed a model NuGet package (e.g. RustODotnet.Models.PPOCRv6.Tiny) or copied model files with <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory> in your .csproj.
• iOS / Swift: Verify that you added pod 'RustO-Models-PPOCRv6-Tiny' to ios/Podfile and executed pod install.
• Android: Ensure rusto-models-ppocrv6-tiny is in app/build.gradle and that you passed an Android Context to RustO.initialize(context).

2. Android: UnsatisfiedLinkError or Missing JNI Symbols

Symptom

java.lang.UnsatisfiedLinkError: dlopen failed: library "librusto.so" not found.

Resolution

Ensure your app's build.gradle does not filter out supported ABIs. Add the standard ABI splits in android.defaultConfig.ndk:

android {
    defaultConfig {
        ndk {
            abiFilters 'arm64-v8a', 'armeabi-v7a', 'x86_64', 'x86'
        }
    }
}

3. React Native: "The package '@rustors/react-native' doesn't seem to be linked"

Symptom

Error when calling initialize() or detectText() in React Native.

Resolution

1. Bare React Native:
   • iOS: Run cd ios && pod install, then rebuild using npm run ios.
   • Android: Clean Gradle cache with cd android && ./gradlew clean, then rebuild.
2. Expo: Custom native C/Rust libraries cannot run in the pre-built Expo Go client. You must generate a native development build:

   npx expo run:ios
   # or
   npx expo run:android
   

4. Out of Memory (OOM) on High-Resolution Camera Photos

Symptom

Application crashes with memory exhaustion when scanning high-resolution photos (48MP, 108MP).

Resolution

Constrain the maximum image dimension in OcrRunOptions before passing to neural inference:

const safeOptions = {
  maxSideLen: 1600, // Downscales before memory allocation
  detection: {
    limitSideLen: 960,
    limitType: 'max',
  },
};

5. Faint or Dotted Thermal Receipts Not Detected

Symptom

Text on thermal paper or dot-matrix receipts is skipped or partially recognized.

Resolution

Enable 2x2 morphological dilation and lower the binarization threshold:

const receiptOptions = {
  textScore: 0.45,
  postprocess: {
    useDilation: true, // Connects faint/broken characters
    threshold: 0.25, // Lowers pixel cutoff
    unclipRatio: 2.2, // Expands polygon boundaries
  },
};

6. Web & React: WebAssembly Blocked or Content Security Policy (CSP) Violations

Symptom

Browser console logs errors when initializing @rustors/web or @rustors/react:

• EvalError: Refused to compile or instantiate WebAssembly module because 'wasm-unsafe-eval' is not an allowed source of script...
• Refused to connect to 'https://cdn.jsdelivr.net/...' because it violates the following Content Security Policy directive...
• SecurityError: Failed to construct 'Worker': Script at 'blob:...' cannot be accessed from origin...

Root Cause

Enterprise deployment headers or strict Content Security Policy (CSP) definitions block WebAssembly compilation, remote asset downloading from CDNs, or Web Worker instantiation.

Resolution

Add the necessary CSP directives to your server HTTP response headers (or <meta http-equiv="Content-Security-Policy"> tag):

Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'wasm-unsafe-eval' https://cdn.jsdelivr.net;
  connect-src 'self' https://cdn.jsdelivr.net blob:;
  worker-src 'self' blob:;
  img-src 'self' data: blob:;

1. WebAssembly Compilation: Modern Chromium, Firefox, and Safari require 'wasm-unsafe-eval' (or legacy 'unsafe-eval') under script-src to execute WebAssembly.instantiate().
2. CDN Assets: If models or .wasm files are loaded from jsDelivr, include https://cdn.jsdelivr.net in both script-src and connect-src.
3. Web Worker Fallback: If worker-src is restricted and cannot be relaxed, configure @rustors/web to run synchronously on the main thread:

   await initialize({
     worker: false, // Disables Web Worker bridge, runs in main thread
     ...
   });