HKUDS/Vibe-Trading · error · RuntimeError

RapidOCR not installed: pip install rapidocr_onnxruntime

Error message

RapidOCR not installed: pip install rapidocr_onnxruntime

What it means

Raised by RapidOCREngine.recognize when the rapidocr_onnxruntime package cannot be imported. The engine lazily checks availability via is_available() and refuses to run OCR on a machine where the dependency was never installed or is installed in a different environment. It is a missing-dependency RuntimeError, not a model or image problem.

Source

Thrown at agent/src/tools/ocr/rapid_ocr.py:32

    def __init__(self) -> None:
        # Lazy init: RapidOCR() loaded inside is_available() / recognize().
        # _select_first_local() probes every registered engine, so __init__
        # must stay cheap (attribute assignment only).
        self._engine = None

    def is_available(self) -> bool:
        try:
            from rapidocr_onnxruntime import RapidOCR  # type: ignore
            if self._engine is None:
                self._engine = RapidOCR()
            return True
        except ImportError:
            return False

    def recognize(self, image: np.ndarray) -> str:
        if not self.is_available():
            raise RuntimeError("RapidOCR not installed: pip install rapidocr_onnxruntime")
        result, _ = self._engine(image)
        if not result:
            return ""
        return "\n".join(item[1] for item in result)


# Self-register to built-in engine table
from src.tools.ocr.engine import register_builtin  # noqa: E402

register_builtin("rapid", RapidOcrEngine)

View on GitHub (pinned to 80ffdda44c)

Solutions

1. pip install rapidocr_onnxruntime into the exact interpreter the agent runs under (python -m pip install rapidocr_onnxruntime)
2. Verify with: python -c "import rapidocr_onnxruntime" in the agent's environment
3. If OCR is optional, call is_available() before recognize() and degrade gracefully
4. In Docker, add the package to the image and rebuild

Example fix

// before
engine = RapidOCREngine()
text = engine.recognize(img)
// after
engine = RapidOCREngine()
if not engine.is_available():
    text = ""  # or log warning / skip OCR
else:
    text = engine.recognize(img)

from agent.src.tools.ocr.rapid_ocr import RapidOCREngine
engine = RapidOCREngine()
if not engine.is_available():
    raise SystemExit("Install rapidocr_onnxruntime or disable OCR features")

def ocr_ready(engine: RapidOCREngine) -> bool:
    return engine.is_available()

try:
    text = engine.recognize(img)
except RuntimeError as e:
    if "not installed" in str(e):
        text = ""  # graceful degradation
    else:
        raise

When it happens

Trigger: Calling agent/src/tools/ocr/rapid_ocr.py recognize(image) on any process where `import rapidocr_onnxruntime` fails: package not installed, installed in another venv/conda env, or the runtime Python used by the agent differs from the one where deps were pip-installed.

Common situations: Fresh clones without optional extras; Docker images that omitted the OCR extra; CI environments; deploying the agent with a system Python while rapidocr was installed in a project venv; onnxruntime wheel incompatibility causing the import to fail indirectly.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• invalid alpha_id
• alpha_id not found
• invalid period: {exc}
• too many running benches; wait for one to finish
• invalid job_id

AI-assisted analysis of HKUDS/Vibe-Trading@80ffdda44c (2026-08-28). Data as JSON: /api/errors/368b4f383e2d9007. Report an issue: GitHub.