Troubleshooting

Common issues and solutions when working with Valohai Notebooks.

Choosing a Docker Image

You can use any public Docker image as your notebook base. Popular choices include:

• Jupyter TensorFlow Notebook — Pre-configured TensorFlow + Jupyter

• PyTorch Official Images — PyTorch with CUDA support

• python:3.12 — Minimal Python base (Valohai installs Jupyter automatically)

Image Doesn't Have Jupyter

No problem. If your Docker image doesn't include Jupyter Notebook or Jupyter Lab, Valohai installs it automatically during startup.

This adds a few minutes to the initial launch time but ensures any Python-based image works as a notebook environment.

Custom Package Requirements

If you need specific versions of libraries or dependencies:

Option 1: Install on-the-fly

Run installation commands directly in a notebook cell:

!pip install matplotlib==3.5.0 scikit-learn

Packages installed this way persist for the duration of your notebook session but won't be included if you stop and restart.

Option 2: Use a custom Docker image

For persistent dependencies, build a custom image with your requirements pre-installed:

FROM python:3.12
RUN pip install matplotlib==3.5.0 scikit-learn torch

Push this image to a registry your organization can access, then select it when launching your notebook.

Notebook Won't Start

If your notebook stays in "Starting" status for more than 10 minutes:

Check your environment availability

The selected environment might be at capacity or unavailable. Try:

• Selecting a different environment in your project settings

• Waiting a few minutes and retrying

• Contacting your platform administrator

Check your Docker image

If using a custom image:

• Verify the image exists and is accessible

• Confirm it's a valid Linux-based Python environment

• Check that your organization's data stores have network access to the registry

Notebook Disconnects or Crashes

Out of memory errors

If your notebook crashes with memory errors:

• Select an environment with more RAM when launching

• Break large datasets into smaller chunks

• Clear cell outputs periodically (Cell > All Output > Clear)

Can't Access Files or Data

Inputs not appearing

If files you configured as inputs aren't available:

• Check that paths use VH_INPUTS_DIR: os.getenv('VH_INPUTS_DIR')

• Verify the data store credentials are configured correctly

• Confirm the file path in your input URL is correct

Outputs not saving

If files aren't appearing in your execution's outputs:

• Write files to /valohai/outputs/ or use valohai.outputs().path()

• Verify the file is written before stopping the notebook

• Check file permissions (notebooks run as a non-root user)