Each entry is a symptom, its usual cause and the fix. Before sharing logs, remove any document text or image data from them.

​
npm ci fails with EPERM

Cause: npm can’t write to its cache. Fix: use a scoped cache: npm ci --cache /tmp/redact-npm-cache. If the error names another path, fix permissions there.

​
npm ci or the first analysis fails with “no space left on device”

Cause: Redact needs about 2.8 GB for node_modules, about 550 MB for models, and about 550 MB more for Playwright’s Chromium if you run the browser tests. Fix: free space, then rerun. See How to clear the model cache and free disk space.

​
npm run qvac:ocr-smoke fails with ENOENT and stat "…/.qvac"

Cause: the OCR script’s QVAC worker keeps its registry in ~/.qvac, and that path is a broken symlink or isn’t writable. Fix: remove the broken link and create a real folder with mkdir ~/.qvac, then rerun.

​
The service fails to start with a missing plugin or native module

Cause: an interrupted install left @qvac/sdk without its native addons, or the platform isn’t supported. Fix: delete node_modules, run npm ci again, and check your OS and Node version against requirements and QVAC’s system requirements.

​
The first analysis takes several minutes

Cause: it downloads about 550 MB of models, which takes a few minutes depending on your connection, then loads them. The service terminal prints many [QVACRegistryClient] [INFO] lines while it downloads. Fix: none needed. Later runs take roughly 20–30 seconds of OCR per page. To download ahead of time, see How to download the models.

​
/health says ready, but the models say not_loaded

Cause: models load on the first analysis, not at startup. Fix: none needed. Run one analysis and check again.

​
Analysis says the local analyzer is busy

Cause: the service runs one analysis at a time and answers 409 busy to any other. A previous analysis, from another tab, a closed tab or a test run, still holds the slot. Cancelling in the browser stops waiting but doesn’t stop inference already running. Fix: wait for it to finish; each page times out after 180 seconds. If it doesn’t clear, stop the service with Ctrl+C and start it again. Meanwhile, select Continue without local analysis to mark by hand.

​
The service logs Local decisions did not match the OCR blocks

The browser shows that local analysis is unavailable. Cause: Laya returned a different number of answers than there were OCR lines, so the page’s suggestions were rejected. Fix: select Try again. If it repeats, check that qvac-service/reasoning.ts passes one state per OCR line to decide(). The review screen still lets you mark by hand.

​
Suggestions miss fields you expected

Cause: suggestions depend on the privacy level, your Additional direction text, OCR quality and a small 421M decision model. Fix: describe what to cover in the direction, choose Confidential for financial details, and always add manual marks for anything missed. To tune what Laya looks for, see How to ask Laya your own questions.

​
Outlines sit on the wrong text

Cause: OCR boxes are in pixels of the analysed raster. Something converted them against a different size or forgot a rotation. Fix: run npm test; the geometry tests cover conversion and rotation. See OCR boxes and rotation.

​
Done stays disabled

Cause: at least one suggestion on some page is neither accepted nor rejected. Fix: go through every page and resolve each suggestion.

​
Playwright says Executable doesn't exist at …/ms-playwright/…

Cause: Playwright’s browser isn’t installed. Fix: npx playwright install chromium.

​
Manual-workflow browser tests fail while the service is running

Cause: those tests expect analysis to be unavailable, so the review screen appears at once. With the service up, the page is still analysing. Fix: stop qvac:service before npm run test:e2e.

​
The live browser test is skipped

Cause: it only runs with REDACT_LIVE_QVAC=1, in the desktop project. Fix: start the service and the app, then REDACT_LIVE_QVAC=1 npx playwright test e2e/offline-qvac-workflow.spec.ts --project=desktop.

​
typecheck fails while a build is running

Cause: both write Next.js generated files. Fix: run them one after the other.

​
QVAC cache is incomplete

Cause: the offline commands need the OCR detector, OCR recognizer and Laya in .qvac/models. Fix: download the models while online.

​
The offline command fails on Linux or Windows

Cause: qvac:offline and qvac:service:offline use macOS sandbox-exec. Fix: run npm run qvac:service with the machine disconnected from the network instead.

​
The evaluation passes but still misses a field

Cause: the gate passes at 0.7 precision, recall and F1, so a case can pass with a miss. Fix: read falseNegatives per case. Keep reviewing exports by eye. See About measuring suggestions.