---
title: Debug a failing attempt
description: Find why a failed attempt did what it did.
---
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reeval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

When an attempt fails, read the phase trace and the transcript to see what the harness did.

## Print the trace

The `-v` flag prints each attempt's phase trace as the attempt runs. The phase on a line is `plan`, `image`, `container`, `env`, `broker`, `harness`, `check`, `judge`, `gateway`, or `teardown`. With `-v`, a passing attempt prints its detail lines.

Print the phase trace for the run.

```bash
npx reeval run -v
```

Each line starts with the attempt's tag. This trace follows the evaluation in [Evaluate](/evaluations/evaluate), from the pinned checkout to the hidden test:

```text
[adds#1 fake] 15:04:40 env       workspace github:sindresorhus/camelcase#v10.0.0 at 328428291b2f (92160 bytes of tar, with a .git) in 25ms
[adds#1 fake] 15:04:40 env       workspace snapshot taken: the diff starts here
…
[adds#1 fake] 15:04:41 check     assert ✓ the repo's tests pass (toSucceed, pass)
[adds#1 fake] 15:04:41 check     assert ✓ toHaveFile readme.md (toHaveFile, pass)
[adds#1 fake] 15:04:41 check     assert ✓ the option works (toSucceed, pass)
```

This trace comes from the example's scripted agent, so its tag reads `fake`. For a runnable project, see [`with-existing-codebase`](https://github.com/invertase/reeval/tree/main/examples/with-existing-codebase).

After the attempt's tag, a failed command assertion has this shape.

```text
12:50:01 check     $ test -f src/user.test.ts → exit 1 · 4ms
```

The `-vv` flag adds raw payloads, container commands under the `docker` phase, request headers, and DNS decisions. `--trace` is the same flag. The terminal prints a short payload. The `trace.ndjson` file keeps the rest.

Print the raw trace for the run.

```bash
npx reeval run -vv
```

reeval replaces secret values with `[REDACTED]` in the trace.

For more information about every `reeval run` flag, see [reeval run](/reference/cli#reeval-run).

## Open the debug directory

The `.reeval/debug` directory holds one directory per run. Each attempt writes its own files there, so a run with no attempt writes no directory. Git ignores it with the rest of the `.reeval/` directory.

Each run keeps the newest debug directories, set by [`debug.keep`](/reference/options#debug), and [`reeval clean`](/reference/cli#reeval-clean) removes the rest.

Attempt files sit at the `.reeval/debug/<run id>/<evaluation>/<cell>/<n>/` path. The evaluation and cell names are slugs, each with a short hash.

Open the `debug.log` file for that trace. Each line has a full timestamp.

```text
2026-09-26T12:50:01.234Z check     $ test -f src/user.test.ts → exit 1 · 4ms
```

The `requests.ndjson` file records one JSON object for each request the egress gateway handles. reeval writes the `trace.ndjson` file for a failing attempt and for every attempt with `-vv`. The first line of the `trace.ndjson` file counts entries the buffer dropped. To cap that file, set [`debug.traceBufferMb`](/reference/options#debug).

For more information, see [the studio's **Debug** tab](/results/inspection/studio).

## Read a transcript

The `transcript.jsonl` file lists every message and tool call of an attempt, in order. reeval writes that file for an attempt with a turn, at the `.reeval/runs/<run id>/<evaluation>/<cell>/<n>/transcript.jsonl` path.

Each line is one JSON object. A turn starts with a `prompt` line, continues with that turn's events, and ends with a `turn-end` line carrying `status` and `durationMs`. A tool line names the tool and includes the input and the output. The `transcript.jsonl` file keeps the final message whole.

A prompt line has these fields.

```json
{
  "ts": "2026-09-27T16:10:34.029Z",
  "atMs": 0,
  "turn": 0,
  "type": "prompt",
  "text": "Add a Vitest test for getUserId."
}
```

To also write the `transcript.raw.jsonl` file in that directory, one stream part per line, set [`REEVAL_RAW_TRANSCRIPT`](/reference/environment-variables#reevalrawtranscript).

## Read the workspace and artifacts

The workspace goes when the sandbox stops. reeval keeps what the agent left in it in the attempt's `.reeval/runs/<run id>/<evaluation>/<cell>/<n>/` directory:

| File | Holds |
| :--- | :--- |
| `diff.patch` | The workspace diff, from the snapshot after setup to the end of the attempt |
| `artifacts/<name>.png` | Screenshots from `c.capture()` |
| `judge-input.json` | What each `c.judge()` call received |

## Reference

For more information about the `debug.keep` and `debug.traceBufferMb` options, see [`debug`](/reference/options#debug). For more information about the variables that change what reeval prints and writes, see [`REEVAL_DEBUG`](/reference/environment-variables#reevaldebug) and [`REEVAL_NO_REPORT_HINT`](/reference/environment-variables#reevalnoreporthint). For more information about a redacted bug report, see [reeval report](/reference/cli#reeval-report).