IFU050(01) Troubleshooting

Installation

npm install fails with 401 Unauthorized

Your auth token is missing or expired. Tokens expire after 12 hours.

export CODEARTIFACT_AUTH_TOKEN=$(aws codeartifact get-authorization-token \
  --domain novarumdx \
  --domain-owner 945969778369 \
  --region eu-west-2 \
  --query authorizationToken \
  --output text \
  --profile novarumdx-sdk)

Then run npm install again.

If the error persists, check that your .npmrc file is in the project root alongside package.json, and that it contains the ${CODEARTIFACT_AUTH_TOKEN} placeholder correctly. The $ and braces must be present.

Still 401 even though your token is fresh

If the token is valid and the project .npmrc is correct but npm still returns 401, a global npm setting may be overriding your project configuration. Check what npm actually resolves:

npm config get registry
cat ~/.npmrc

A bare registry= line in your user-level ~/.npmrc applies to every package that is not explicitly scoped, so ordinary dependencies are fetched from the wrong registry and fail to authenticate. It should read https://registry.npmjs.org/. Your project .npmrc handles the @novarumdx scope on its own, so the global registry does not need to point anywhere else.

To confirm this is the cause, install once while ignoring the user config:

npm install --userconfig /dev/null

If that succeeds, the global config is at fault. This failure is easy to misdiagnose because it looks identical to an expired token, so check it before fetching another token.

npm install fails with "profile not found"

The novarumdx-sdk AWS profile has not been set up on this machine.

aws configure --profile novarumdx-sdk

Use the credentials provided by NovarumDX.

WASM files missing after install

The postinstall script copies the WASM files automatically. If they are missing:

1. Check that the postinstall step ran. Look for output containing copy-wasm during npm install.

2. If it was skipped, for example because the environment uses --ignore-scripts, run it manually:

node node_modules/@novarumdx/ndx-imaging-web/scripts/copy-wasm.js

• If you are using a React project (Vite), the files should appear in public/.

• If you are using a vanilla JS project, the files should appear in your project root.

Camera

Camera not starting - permission denied

The browser blocked camera access. Click the camera icon in the address bar, select Allow, and refresh the page.

On HTTPS sites, the browser may remember the denial. If clicking the icon shows Blocked and you cannot change it, clear site permissions in browser settings and try again.

Camera not starting on a mobile device

Camera access requires HTTPS on any device other than localhost. The easiest way to test on a phone is a tunnel that gives a public, already-trusted HTTPS URL. Install cloudflared (no account needed), run your dev server, then in a second terminal run cloudflared tunnel --url http://localhost:<your-dev-port> and open the https://<random>.trycloudflare.com URL it prints on your phone. React/Vite: allow the tunnel host in vite.config.js via server.allowedHosts.

Camera in use by another tab or app

Close any other browser tab that is using the camera, or quit any application using the camera, such as video conferencing tools. Then refresh and try again.

Black screen - camera opens but no image

This usually means the camera opened but the video stream has not started yet. Check:

1. Your device has more than one camera. The SDK requests the default rear camera. If no rear camera is found it may fall back to a front camera, which can appear black on some devices if permissions differ.

2. Try specifying a cameraDeviceId explicitly:

const devices = await navigator.mediaDevices.enumerateDevices();
console.log(devices.filter(d => d.kind === 'videoinput'));
// pick the correct deviceId and pass it to cameraDeviceId

React

"Cannot find module '@novarumdx/ndx-imaging-web/react'"

Check the package is installed and that you are importing from the /react subpath:

import { useNDXReader, NDXReaderView } from '@novarumdx/ndx-imaging-web/react';

If the import still fails, delete node_modules and reinstall so the subpath export is picked up.

Vite: WASM or worker assets return 404

Vite serves the public/ folder at the site root. Make sure the WASM files copied in by the postinstall step are in public/ (see "WASM files missing after install" above). If you host the app under a sub-path, set base in vite.config.js accordingly.

Camera works on desktop but not on your phone

See "Camera not starting on a mobile device" above - use the cloudflared tunnel and add the tunnel host to server.allowedHosts in vite.config.js.

PMF story / image capture

Images are null - captureImages is true but imageUrl is always null

The device or browser does not support OffscreenCanvas. This is required for image capture.

Supported browsers:

• Chrome 69+

• Firefox 105+

• Safari 16.4+

If you are on a supported browser, check the browser console for errors. If you see a SecurityError, the site may need to be served over HTTPS.

IndexedDB images not being cleared

Call clearAllPmfStoryImages() on page load to remove any images left over from an interrupted scan.

Memory growing across multiple scans

After displaying story images, call revokeStoryImageUrls(resolvedFrames) when navigating away from the results view. Each Blob URL holds a reference to memory until it is explicitly released.

Runtime and scanning

[NDXReader worker] 'init' failed: SyntaxError: Unexpected token '<', "<!DOCTYPE "... is not valid JSON

The cassette config path does not resolve, so the dev server returns index.html instead of a 404 and the worker tries to parse HTML as JSON. Verify the .unified.json sits at the exact path config points to (public/ is the web root, so public/models/x/x.unified.json is referenced as /models/x/x.unified.json). Confirm with curl http://localhost:<port>/<your-config-path> - it must return JSON, not HTML.

[NDXReader worker] 'new' failed: TypeError: Cannot read properties of null (reading 'clearSession')

A consequence of a failed init, not a separate fault. Fix the init error logged at page load; this message disappears once the engine initialises.

General

Scan never completes - progress bar stalls

The scanner needs a minimum number of well-aligned frames before running analysis. If the progress bar is not filling, check:

1. The cassette is fully in frame and not at an angle.

2. Lighting is even, with no harsh shadows across the strip window.

3. The camera is close enough. The cassette should fill most of the viewfinder.

The onWarnings callback will fire with warnCode 1 for baseline problems or 2 for exposure problems if there is a quality issue.

Results vary between scans of the same cassette

A small amount of variation is expected. For the most consistent results:

1. Hold the device steady. Mount it if possible.

2. Use consistent lighting, such as daylight or a lightbox, rather than overhead fluorescent lighting.

3. Enable torchEnabled: true on supported devices for more consistent illumination.

If variation is larger than expected, contact NovarumDX with a PMF story from the failing scans.

Sending diagnostic data to NovarumDX support

If you are reporting a bug or unexpected result, log the raw strips and pmfStory from your onSuccess callback and send them to NovarumDX support:

onSuccess: (strips, pmfStory, diagnostics) => {
  console.log('strips:', JSON.stringify(strips, null, 2));
  console.log('diagnostics:', JSON.stringify(diagnostics, null, 2));
  console.log('pmf story length:', pmfStory.length);
},

Copy the console output and include it with your support request.

Support

For access credentials, cassette configuration files, or integration assistance, contact your NovarumDX representative or technical account manager.

For support requests and issue tracking, use the SDK Service Desk.