Troubleshooting

Startup fails around OCR

Check that Tesseract 5.x is installed and that tessdata/vie.traineddata exists relative to the process working directory. The production service uses that exact path and language. If initialization fails, the service logs a warning and OCR calls return OCR Disabled.

The request returns HTTP 500

The controller intentionally maps every exception in CSV parsing, image decoding, processing, OCR, and grading to an empty 500 response. Inspect server logs for the exception. Check both multipart names (image and answers), the answer-key header, the image file, and the working-directory assumptions for tessdata and data/debug.

The application does not expose a structured error body or a product-specific 4xx contract, so do not infer the cause from the response body.

Answers are empty or wrong

Confirm that the sheet matches the fixed 40-question, four-column layout and that the image can be aligned or resized to the expected 800x1200 canvas. Review the generated overlay under data/debug/ when available. A double mark is returned as a sorted multi-letter value such as AC and will not match a single-letter answer key.

OCR text is unexpected

The name and class crops are fixed coordinates. In the test profile, OCR always returns Dummy Student; that is expected and is not evidence about production Tesseract output. Do not share uploaded sheets or debug overlays in an issue without removing sensitive data.