docs/hf-space-libvtk-error.md

# OpenCascade (OCP) Missing Shared Library Error

**Issue:**
The HF Space Docker container builds correctly and the Gradio app runs, but the actual geometry generation subprocess fails with:
`ImportError: libvtkWrappingPythonCore3.10-9.3.so: cannot open shared object file: No such file or directory`

**Root Cause:**
`cadquery-ocp` (OpenCascade) from conda-forge has implicit C++ dependencies that aren't being satisfied by the base `continuumio/miniconda3:latest` (Debian-based) Docker image. Specifically, `libvtk` (Visualization Toolkit) components are missing at runtime.

**Why this happened:**
When installing `ocp` via `conda install -c conda-forge ocp`, Conda usually resolves and installs all required C++ shared libraries (like vtk, xorg, qt, etc). However, sometimes `conda-forge` packages assume the host system has certain graphical/X11 or VTK libraries pre-installed, or the conda environment path isn't exposing the `libvtk` binaries correctly to the subprocess `LD_LIBRARY_PATH`.

**Next Steps to Fix (Next Session):**
1. We need to identify exactly which system package provides `libvtkWrappingPythonCore3.10-9.3.so`. It might require installing VTK via conda explicitly (`conda install -c conda-forge vtk`), or installing it via `apt-get` in the Dockerfile.
2. Alternatively, using a different base image like `condaforge/miniforge3` instead of `continuumio/miniconda3` often resolves these hidden `conda-forge` shared library linking issues.
3. Once the VTK library issue is patched in the Dockerfile, the CAD engine will successfully render.

**Current Status:**
- UI: Working
- Docker Build: Passing
- Fallback Prompt Routing: Working
- CAD Execution: Failing on `libvtk` import

(Logged at 2026-04-10 22:25 PDT)