---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/observability/debug-a-failed-session
markdown_url: https://steel.dev/docs/observability/debug-a-failed-session.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Debug a failed session
description: Start from a session's ID, and read its signals, recording, logs and agent traces to find out why it failed.
summary: Start from a session's ID, and read its signals, recording, logs and agent traces to find out why it failed.
type: how-to
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/observability/live-view.md
  - https://steel.dev/docs/observability/embed-a-live-browser.md
  - https://steel.dev/docs/observability/hand-control-to-a-human.md
  - https://steel.dev/docs/observability/recordings.md
  - https://steel.dev/docs/observability/logs.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Debug a failed session

Steel keeps a record of each session, and you read that record to find out why a run failed. The record holds the reason that the session ended, what Steel saw during the run, a video of the browser, and logs of its pages and actions. Read it in this order: the release reason and signals, then the recording, then the logs and agent traces. Each step takes longer to read than the one before. Steel keeps this data for your plan's data retention period. See [Limits](https://steel.dev/docs/platform/limits).

## Before you begin

Put your Steel API key in the `STEEL_API_KEY` environment variable, and install the Steel SDK with `npm install steel-sdk` or with `pip install steel-sdk` in a [virtual environment](https://steel.dev/docs/reference/sdks/python#install). In Go and Rust, each program is the `main.go` of a module or the `src/main.rs` of a Cargo project, set up as the [Go](https://steel.dev/docs/reference/sdks/go#install) and [Rust](https://steel.dev/docs/reference/sdks/rust#install) SDK pages show.

## 1. Find the session

Start from the session ID. Log each session's ID when your code creates it, next to your own job's ID.

If you do not have the ID, find the session by what you know about it:

- Its metadata, such as the job ID or customer that you set when you created it. See [Add metadata](https://steel.dev/docs/sessions/metadata).
- Its `status` or `releaseReason`, which say how it ended.
- Its signals, which say what Steel saw during the run, such as a CAPTCHA.
- The time it was created, with `createdAfter` and `createdBefore`.

This program lists one job's sessions from November 1, 2026, with how each one ended. Replace the metadata and dates with yours.

**TypeScript**

```ts file=find-sessions.mts
import Steel from "steel-sdk";

const client = new Steel();

for await (const session of client.sessions.list({
  metadata: { job_id: "job-1042" },
  createdAfter: "2026-11-01T00:00:00Z",
  createdBefore: "2026-11-02T00:00:00Z",
})) {
  console.log(session.id, session.releaseReason, session.signals);
}
```

**Python**

```python file=find_sessions.py
from steel import Steel

client = Steel()

for session in client.sessions.list(
    metadata={"job_id": "job-1042"},
    created_after="2026-11-01T00:00:00Z",
    created_before="2026-11-02T00:00:00Z",
):
    print(session.id, session.release_reason, session.signals)
```

**Go**

```go file=main.go
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/steel-dev/sdk/go"
)

func main() {
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context) error {
	client := steel.NewClient()

	iter := client.Sessions.ListAutoPaging(ctx, steel.SessionListParams{
		Metadata:      steel.F(map[string]string{"job_id": "job-1042"}),
		CreatedAfter:  steel.F(time.Date(2026, time.November, 1, 0, 0, 0, 0, time.UTC)),
		CreatedBefore: steel.F(time.Date(2026, time.November, 2, 0, 0, 0, 0, time.UTC)),
	})
	for iter.Next() {
		session := iter.Current()
		fmt.Println(session.ID, session.ReleaseReason, session.Signals)
	}
	if err := iter.Err(); err != nil {
		return err
	}
	return nil
}
```

**Rust**

```rust file=src/main.rs
use futures_util::StreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = steel_rs::Client::new();

    let sessions = client
        .sessions()
        .list_auto_paging(steel_rs::SessionListParams {
            metadata: Some(std::collections::HashMap::from([(
                "job_id".to_owned(),
                "job-1042".to_owned(),
            )])),
            created_after: Some("2026-11-01T00:00:00Z".to_owned()),
            created_before: Some("2026-11-02T00:00:00Z".to_owned()),
            ..Default::default()
        });
    let mut sessions = std::pin::pin!(sessions);
    while let Some(session) = sessions.next().await {
        let session = session?;
        println!(
            "{} {:?} {:?}",
            session.id, session.release_reason, session.signals
        );
    }
    Ok(())
}
```

In Rust, the program also needs `cargo add futures-util`. Run the program:

**TypeScript**

```sh
npx tsx find-sessions.mts
```

**Python**

```sh
python find_sessions.py
```

**Go**

```sh
go run .
```

**Rust**

```sh
cargo run
```

The program prints one line for each session that matches, with its ID, its `releaseReason` and its `signals`.

A run that went wrong usually ends as a `released` session: your code released it after a task error, or Steel released it at its timeout or after a crash. Its `releaseReason` says which, and it has a recording and logs to read. The list leaves out `failed` sessions unless you pass `status` or `releaseReason`. A `failed` session is one whose browser never started, so it has no recording and no logs, and its `releaseReason`, `startup_failed` or `creation_timeout`, is all there is to read. To list those too, pass `status: "failed"`.

## 2. Check the signals

Retrieve the session. Its `status`, `releaseReason` and `signals` tell you most of what went wrong:

**TypeScript**

```ts
const session = await client.sessions.retrieve(sessionId);
console.log(session.status, session.releaseReason, session.signals);
```

**Python**

```python
session = client.sessions.retrieve(session_id)
print(session.status, session.release_reason, session.signals)
```

**Go**

```go
session, err := client.Sessions.Get(ctx, sessionID)
if err != nil {
	return err
}
fmt.Println(session.Status, session.ReleaseReason, session.Signals)
```

**Rust**

```rust
let session = client.sessions().retrieve(&session_id).await?;
println!(
    "{:?} {:?} {:?}",
    session.status, session.release_reason, session.signals
);
```

**TypeScript**

```text nocopy
released user_requested [ 'bot_detection_triggered', 'captcha_encountered' ]
```

**Python**

```text nocopy
released user_requested ['bot_detection_triggered', 'captcha_encountered']
```

**Go**

```text nocopy
released user_requested [bot_detection_triggered captcha_encountered]
```

**Rust**

```text nocopy
Released Some(UserRequested) [BotDetectionTriggered, CaptchaEncountered]
```

`releaseReason` says why the session ended. Use it to decide where to look next:

| `releaseReason` | What it points to |
| - | - |
| `user_requested` | Your code released the session. The failure is in your task. Read the recording and agent traces. |
| `timeout` or `inactivity_timeout` | The session ran out of time, or nothing drove it. Check whether the agent waited on something, such as a CAPTCHA or a model call. See [Set timeouts](https://steel.dev/docs/sessions/timeouts). |
| `browser_closed` | The browser closed itself, or your agent closed it. This is not a crash. Check the last actions in the agent traces. |
| `creation_timeout`, `startup_failed` or `browser_crashed` | The browser did not start, or it stopped. Create a new session. If it happens again, contact [Support](https://steel.dev/docs/support) with the session ID. |

`signals` says what Steel saw during the run, such as `captcha_encountered`, `bot_detection_triggered` or `proxy_connection_failed`. An empty list does not prove that nothing happened, and the list stays empty until [a few seconds after the session ends](https://steel.dev/docs/observability/signals). [Signals reference](https://steel.dev/docs/reference/signals) explains each one.

## 3. Watch the recording

The recording shows what the browser showed, so it answers questions that logs cannot: whether a page loaded, what a popup covered, or which element the agent clicked.

Open the session viewer, the session's page in the dashboard. Its URL is in `sessionViewerUrl`:

**TypeScript**

```ts
console.log(session.sessionViewerUrl);
```

**Python**

```python
print(session.session_viewer_url)
```

**Go**

```go
fmt.Println(session.SessionViewerURL)
```

**Rust**

```rust
println!("{}", session.session_viewer_url);
```

```text nocopy
https://app.steel.dev/sessions/4d7512b8-4dc9-4058-917f-d984ac3473c6
```

The session viewer plays the recording. Its Agent Traces tab lists each action of the run, such as a click, an input or a navigation. Click a row, and the video moves to that moment. Go to the last action before the failure, and watch what the page did next.

To play the recording in your own app, see [Recordings](https://steel.dev/docs/observability/recordings).

## 4. Read the logs and traces

Read the logs and agent traces when you need the exact order of events, or when you want to search many sessions with code.

- Logs hold what the pages did: requests, responses, console messages and errors.
- Agent traces hold what the agent did: each click, input, scroll and navigation, with the element that it acted on.

**TypeScript**

```ts
const logs = await client.sessions.logs(sessionId);
for (const event of logs.events) {
  console.log(event.timestamp, event.type, event.log.slice(0, 200));
}

const traces = await client.sessions.agentTraces(sessionId);
for (const event of traces.events) {
  console.log(JSON.stringify(event));
}
```

**Python**

```python
logs = client.sessions.logs(session_id)
for event in logs.events:
    print(event.timestamp, event.type, event.log[:200])

traces = client.sessions.agent_traces(session_id)
for event in traces.events:
    print(event)
```

**Go**

```go
import "encoding/json"

logs, err := client.Sessions.Logs(ctx, sessionID, steel.SessionLogsParams{})
if err != nil {
	return err
}
for _, event := range logs.Events {
	text := []rune(event.Log)
	fmt.Println(event.Timestamp, event.Type, string(text[:min(len(text), 200)]))
}

traces, err := client.Sessions.AgentTraces(ctx, sessionID, steel.SessionAgentTracesParams{})
if err != nil {
	return err
}
for _, event := range traces.Events {
	out, err := json.Marshal(event)
	if err != nil {
		return err
	}
	fmt.Println(string(out))
}
```

**Rust**

```rust
let logs = client
    .sessions()
    .logs(&session_id, steel_rs::SessionLogsParams::default())
    .await?;
for event in logs.events {
    let text: String = event.log.chars().take(200).collect();
    println!("{} {} {text}", event.timestamp, event.r#type);
}

let traces = client
    .sessions()
    .agent_traces(&session_id, steel_rs::SessionAgentTracesParams::default())
    .await?;
for event in traces.events {
    println!("{}", serde_json::to_string(&event)?);
}
```

In Rust, this code needs `cargo add serde_json`.

Each response has `events`, `total` and `hasMore`. When `hasMore` is `true`, ask for the next part with the `offset` and `limit` parameters, or narrow the time range with `startTime` and `endTime`. An agent trace event looks like this:

```json nocopy
{
  "type": "click",
  "timestamp": "2026-11-01T18:03:21.345Z",
  "page": { "url": "https://steel.dev/practice/login" },
  "target": {
    "role": "button",
    "accessibleName": "Login",
    "selector": { "css": "form#login > button" }
  }
}
```

Look for the last event before the failure. In the logs, look for failed requests and page errors near that time. In the traces, compare the element that the agent acted on with the element that it should have acted on. [Logs](https://steel.dev/docs/observability/logs) and [Agent traces](https://steel.dev/docs/observability/agent-traces) describe each field.

## 5. Fix the cause

Most causes have a page with the fix:

- An error from the API, such as a limit or an invalid option: [Errors](https://steel.dev/docs/reference/errors).
- A block, a CAPTCHA or a bot check: [Get past bot detection](https://steel.dev/docs/stealth/get-past-bot-detection).
- A proxy that failed: [Proxies](https://steel.dev/docs/stealth/proxies).
- A session that ran out of time: [Set timeouts](https://steel.dev/docs/sessions/timeouts).
- A login that the site did not accept: [Stay signed in across sessions](https://steel.dev/docs/logins/stay-signed-in).
- A live view or a recording that does not show: [Live view](https://steel.dev/docs/observability/live-view) and [Recordings](https://steel.dev/docs/observability/recordings).

## Check that it worked

After the fix, run the task again with the same metadata. A few seconds after the new session ends, run the program in [1. Find the session](https://steel.dev/docs/observability/debug-a-failed-session#1-find-the-session) with dates that include the new run. The new session's line no longer has the signal or the `releaseReason` that pointed to the cause, such as `captcha_encountered` or `timeout`. Then watch its recording, as in [3. Watch the recording](https://steel.dev/docs/observability/debug-a-failed-session#3-watch-the-recording), and check that the agent gets past the step where the old run failed.

## Next steps

- [Troubleshooting](https://steel.dev/docs/troubleshooting): Find an error that you see, and go to the page that explains its fix.
- [Run sessions at scale](https://steel.dev/docs/production/run-sessions-at-scale): Retry failed work safely, and watch signals across many sessions.
- [Prepare for production](https://steel.dev/docs/production/checklist): Check timeouts, retries, limits and monitoring before you send real traffic.
