# 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](https://hub.docker.com/r/jupyter/tensorflow-notebook/tags) — Pre-configured TensorFlow + Jupyter
* [PyTorch Official Images](https://hub.docker.com/r/pytorch/pytorch/tags) — 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:

```shell
!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:

```dockerfile
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)