[FEA]: Enhance load_nvidia_dynamic_lib error message if a library cannot be found #851

Activity

1. github-project-automation

   added this to CCCLon Aug 18, 2025
2. github-project-automation

   moved this to Todo in CCCLon Aug 18, 2025
3. github-actions

   added

   triageNeeds the team's attentionNeeds the team's attention

   on Aug 18, 2025
4. rwgk

   added

   cuda.pathfinderEverything related to the cuda.pathfinder moduleEverything related to the cuda.pathfinder module

   on Aug 18, 2025
5. rwgk

   added this to the pathfinder-nvmath-support milestone on Aug 18, 2025
6. rwgk

   changed the title [-][FEA]: Add force_load_nvidia_dynamic_lib[/-] [+][FEA]: Enhance `load_nvidia_dynamic_lib` error message if a library cannot be found[/+] on Aug 18, 2025
7. rwgk commented on Aug 18, 2025

   

   rwgk

   on Aug 18, 2025

   Contributor

   More actions

   Discussed offline:

   • We want to create a troubleshooting page in the a cuda-pathfinder documentation (that still needs to be added: Add Sphinx docs for cuda.pathfinder #760)
   • Then add a URL pointing to the troubleshooting page from the RuntimeError reporting that the requested library could not be found.

   Mock-up (non-existing URL):

   cuda.pathfinder._dynamic_libs.load_dl_common.DynamicLibNotFoundError: Failure finding "libnotalib.so"
   
   Please see https://nvidia.github.io/cuda-python/cuda-pathfinder/latest/troubleshooting.html for help.
   
   No such file: libnotalib.so*, No such file: /usr/local/cuda-12.9/lib64/libnotalib.so
   ...
   

   👍React with 👍1Reacted by Yevhenii Havrylko
8. leofang

   modified the milestones: pathfinder-nvmath-support, cuda-pathfinder parking lot on Aug 30, 2025
9. rparolin

   removed

   triageNeeds the team's attentionNeeds the team's attention

   on Jan 19, 2026
10. rparolin

    removed this from the cuda.pathfinder backlog milestone on Apr 2, 2026
11. rparolin

    added

    featureNew feature or requestNew feature or request

    on May 21, 2026
12. aryanputta commented on Jul 4, 2026

    

    aryanputta

    on Jul 4, 2026

    Contributor

    More actions

    I would like to work on this, following the plan in the comment above: a troubleshooting page in the cuda-pathfinder docs, plus the URL appended to the not-found error messages.

    I have this implemented and validated locally (ruff, mypy-pathfinder, and the pathfinder unit tests pass; the new page follows the existing docs layout, so #760 being done unblocks this):

    • New docs/source/troubleshooting.rst: how to read the "Failure finding" message, the search order (wheels, conda, OS loader, CUDA_PATH/CUDA_HOME), common causes and fixes, and how to report an issue. Content is derived from the load_nvidia_dynamic_lib docstring.
    • A small _utils/troubleshooting.py with the URL constant and an append_troubleshooting_url() helper, applied to the raise_not_found sites (dynamic, bitcode, static) and the driver-library message, matching the mock-up format.

    Happy to open the PR if assigned, and to trim the scope to the dynamic-lib error only if that is preferred.