Troubleshoot NVIDIA NIM for Image OCR (NeMo Retriever OCR)#
Use this documentation to troubleshoot NVIDIA NIM for Image OCR (NeMo Retriever OCR).
The NIM Fails to Start#
Confirm that you accepted the container license terms in the NGC Catalog, that the NVIDIA driver and Container Toolkit are current, and that the selected GPU is listed in the support matrix.
For Hugging Face model downloads, set both NIM_ENGINE_MODEL_DOWNLOAD_PROVIDER=hf and HF_TOKEN. To download NGC model artifacts instead, set both NIM_ENGINE_MODEL_DOWNLOAD_PROVIDER=ngc and NGC_API_KEY.
The NIM Fails with an Out-of-Memory Error#
Additional OCR engines, larger batches, and expanded CUDA graph capture or warmup shapes increase VRAM use. To reduce the footprint, start with the latency defaults:
-e NIM_PERFORMANCE_MODE=0 \
-e NIM_ENGINE_COUNT=1 \
-e NIM_PIPELINE_MAX_BATCH_SIZE=1
If you customized CUDA graph capture or warmup shapes, remove those overrides and retry. Confirm that the selected GPU is listed in the support matrix.
list-model-profiles Is Not Available#
Starting in release 2.0.0, the NIM does not use Triton model profiles. Configure the OCR model variant, precision, performance mode, and engine settings with the variables in Environment Variables for NVIDIA NIM for Image OCR (NeMo Retriever OCR).
OCR Accuracy Is Lower Than Expected#
Confirm that the correct model variant is selected. The multilingual model is the default. For English-only documents, compare results with NIM_ENGINE_MODEL_VARIANT=english.
Input resolution, compression artifacts, rotation, and very small text can affect recognition quality. Use supported JPEG, JPG, or PNG inputs and preserve sufficient resolution for the text being recognized. For performance-sensitive workloads, prefer JPEG input to enable batched image decoding. For details, see Optimize Image Decoding.