---
title: 'How do I debug a run that went wrong?'
description: 'Log with plain console.*, read the run timeline the runtime records for you, and inspect the same runs from the CLI.'
position: 3
---

# How do I debug a run that went wrong?

> You log with plain `console.*` and read the timeline the runtime already
> records. There is no tracer to register and no exporter to configure.

Inside a tool or a workflow step, the runtime captures every `console.*` line and
stamps it with the run it belongs to, the trace of the invocation that produced
it and the step that was executing. You thread no run id through your own code.
Pass the variable data as an object rather than in the message. Only an object
field stays filterable later:

```ts
console.info('email sent', { to, templateId }); // `to` is filterable
console.info('email sent to ' + to); // it is not
```

You get the run timeline without setting anything up. Each `'use step'` appears
with its timing, its result and every retry attempt. Agent turns show the tools the model invoked
with their inputs and outputs, and calls through `stackbone.ai` record latency
and token usage. A run parked on an approval reads as interrupted until the
decision arrives.

You do not need Studio open to read any of it:

```sh
stackbone runs list
stackbone runs get <run-id>
stackbone logs tail --run <run-id> --follow
```

Drop `--follow` and the tail prints what already happened, then exits, which is
what you want in a script. `--since`, `--until` and `--limit` narrow it further.
Once you know what went wrong, `stackbone runs retry <run-id> --yes` starts a
fresh run from the failed one's input, and `stackbone runs cancel <run-id> --yes`
stops one still in flight. Both change state, so both want `--yes`.

`stackbone dev` serves the same runs and the same timeline locally, so what you
debug on your laptop matches what the deployed box does. When a CLI command
itself fails, re-run it with `--json` and read `error.code` and
`error.suggestion`.

## Read more

- **[Logging and observability](/docs/sdk/platform/observability)**: what the
  timeline records and how to read it.
- **[`stackbone runs`](/docs/cli/reference/runs)** and
  **[`stackbone logs`](/docs/cli/reference/logs)**: every verb and flag.
- **[When registration fails](/docs/home/deployments/troubleshooting)**: for a
  box that never came up in the first place.