# Debug mode

## Introduction

Debugging why a batch has failed by making changes to the configuration and rerunning can be fiddly. To help with debugging in certain situations, ReSim has developed a debug mode which can be used to interact with your image in a live environment.

## Prerequisites

- The [ReSim CLI](https://github.com/resim-ai/api-client) must be installed on your local device
- Your image must include a shell (e.g. `sh` or `bash`) and the `sleep` command.
- You need an experience ID or name
- You also need a batch name or a build ID

## Running a debug session

Run the debug command:

Bash

```
resim debug --project <project-id> --build <build-id> --experience my-test-data
```

In the background, ReSim will launch a new ephemeral environment and run your build image in it. The experience data will be available (read-only) in `/tmp/resim/inputs` as in a standard batch.

If your image is very large, it can take a few minutes to set up the debug environment.

By default, the command that runs in your container will be `sh`, but you can override this by setting the `--command` flag on the `debug` command.

Once the batch is running, you will be dropped into a shell. From this shell, you can run commands as normal to inspect the environment and configuration.

For example, you could:

- check dependencies are installed
- check the input data in `/tmp/resim/inputs` is present and structured correctly
- run entrypoint scripts to see immediate output and debug errors

The debug batch will run for 1 hour or your experience's timeout setting, whichever is longer. After the timeout or when you exit the shell by running `exit` or pressing Ctrl-D, ReSim will terminate the debug batch.

Any files you write to `/tmp/resim/outputs` will be uploaded as in a standard batch for later inspection. Nested output directories are archived by default after the run, except for `/tmp/resim/outputs/logs/`, whose contents remain unarchived.

### Debug mode for multi-container builds

If you have a multi-container build setup, which is described by a docker compose file, you can specify the container you want to bash in using the `--container` flag, which should be the `container_name` parameter that you specify in the compose file for a service.