When opening JupyterLab on your Pod, you may see a blank white page, even when the JupyterLab link in the Pod connection panel says it’s “Ready.” This page provides guidance to help you troubleshoot this issue.
Understanding JupyterLab readiness
When you start a Pod with JupyterLab configured, it periodically pings the JupyterLab server to check its status. When the console displays a “Ready” status, it only means that the Jupyter server /api/status endpoint is responding to HTTP requests, not that JupyterLab has successfully started. It may take additional time to fully load and become usable.
Common causes
A blank JupyterLab page can occur for several reasons, and sometimes multiple issues occur at once:
- Pod still starting up: You might see a blank white screen for some time after starting your Pod. This happens because Pod resources or services aren’t fully initialized yet (even though it may be listed as “Running” in the console).
The best way to check if your Pod is ready to use is by checking the Telemetry tab in the Pod details page in the Runpod console. If a Pod is receiving telemetry, it should be ready to use, but individual services like JupyterLab may take a few minutes to start up.
-
Jupyter service still loading: The Jupyter service may still be spinning up or performing initial setup work.
-
Browser cache issues: If you keep seeing the same blank screen after closing and reopening the JupyterLab link, your browser (or an intermediate layer) might be serving a cached broken response.
-
Network problems: If JupyterLab fails to load or stalls and other sites are also slow, you may have local network or connectivity issues between your machine and the Pod.
-
Misconfigured Pod or template: If JupyterLab never loads despite multiple restarts and long waits, the image or template might not be starting Jupyter on the expected port or path.
Troubleshooting steps
Follow the steps below based on what you’re currently seeing.
Status shows “Initializing”
Wait at least 30 to 60 seconds after starting your Pod before opening JupyterLab. The Pod needs time to fully initialize all services.
Status shows “Ready” but page is blank
-
Wait on the blank screen for at least 60 seconds to allow JupyterLab to finish starting.
-
Try a hard refresh:
- Windows/Linux: Press Ctrl + Shift + R
- Mac: Press Cmd + Shift + R
-
Open the JupyterLab link in a private or incognito browser window to rule out browser caching.
-
If still blank, check your Pod logs in the Runpod console for JupyterLab-related errors or confirmation that Jupyter has started. Look for messages indicating that Jupyter is running on port 8888 (or your configured port). If you don’t see any messages, check the Pod logs for errors.
Runpod only performs the JupyterLab health check on port 8888. If you’re using a different port to expose the service, we recommend changing the port in your template configuration to 8888.
- If you see errors or Jupyter never appears to start, restart the Pod and repeat the steps above.
Repeated restarts
If you restart the same Pod more than three times and JupyterLab never loads, treat this as a configuration or template issue rather than a transient startup delay.
Verify the following:
- You’re using a template that supports JupyterLab on the documented port (typically 8888).
- Any required environment variables or startup commands for Jupyter are correctly set in your template configuration. If you’re not sure, check the template documentation.
If still stuck, share your Pod logs and template configuration with support or in the Runpod Discord.
Runpod does not maintain or provide customer support for community templates. If you encounter issues, contact the template creator directly or seek help on the community Discord. 
