# 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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.valohai.com/notebook-executions/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.