Improve the error message provided when jupyterhub is missing (jupyterlab#18060)

* Improve the error message provided when jupyterhub is missing

Fixes: jupyterlab#18054

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update jupyterlab/labhubapp.py

Co-authored-by: Miro Hrončok <[email protected]>

* Add a test for the improved error message

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Miro Hrončok <[email protected]>

Author: 3 people

jupyterlab/labhubapp.py

@@ -4,6 +4,7 @@
 # Distributed under the terms of the Modified BSD License.
 
 import os
+import sys
 
 from jupyter_server.serverapp import ServerApp
 from traitlets import default
@@ -18,7 +19,27 @@
     from jupyterhub.singleuser.mixins import make_singleuser_app
 except ImportError:
     # backward-compat with jupyterhub < 1.3
-    from jupyterhub.singleuser import SingleUserNotebookApp as SingleUserServerApp
+    try:
+        from jupyterhub.singleuser import SingleUserNotebookApp as SingleUserServerApp
+    except ImportError as e:
+        # jupyterhub is not installed at all
+        venv_info = sys.prefix
+        is_venv = sys.base_prefix != sys.prefix
+        venv_type = "virtual environment" if is_venv else "Python environment"
+
+        error_msg = (
+            f"JupyterHub is not installed and is required to run this application.\n\n"
+            f"Current {venv_type}: {venv_info}\n\n"
+            f"Python sys.path entries searched:\n"
+        )
+        for path in sys.path:
+            error_msg += f"  - {path}\n"
+        error_msg += (
+            f"\nTo fix this issue, install jupyterhub:\n"
+            f"  pip install jupyterhub\n\n"
+            f"Original error: {e}"
+        )
+        raise ImportError(error_msg) from e
 else:
     SingleUserServerApp = make_singleuser_app(ServerApp)
 

scripts/ci_script.sh

@@ -364,6 +364,11 @@ if [[ $GROUP == usage2 ]]; then
     rm -f /tmp/jupyter_log_$$.txt
 
     # Check the labhubapp
+    # Test that the labhubapp fails to start if jupyterhub is not installed
+    # and provides a helpful error message.
+    ($TEST_INSTALL_PATH/bin/jupyter-labhub 2>&1 || true) | tee labhub.log
+    grep -q "JupyterHub is not installed" labhub.log || exit 1
+    # Install jupyterhub and test that the labhubapp starts successfully.
     $TEST_INSTALL_PATH/bin/pip install jupyterhub
     export JUPYTERHUB_API_TOKEN="mock_token"
     $TEST_INSTALL_PATH/bin/jupyter-labhub --HubOAuth.oauth_client_id="mock_id" &