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.
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. 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 and Rust 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.
- Its
statusorreleaseReason, 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
createdAfterandcreatedBefore.
This program lists one job's sessions from November 1, 2026, with how each one ended. Replace the metadata and dates with yours.
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);
}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)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
}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:
npx tsx find-sessions.mtspython find_sessions.pygo run .cargo runThe 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:
const session = await client.sessions.retrieve(sessionId);
console.log(session.status, session.releaseReason, session.signals);session = client.sessions.retrieve(session_id)
print(session.status, session.release_reason, session.signals)session, err := client.Sessions.Get(ctx, sessionID)
if err != nil {
return err
}
fmt.Println(session.Status, session.ReleaseReason, session.Signals)let session = client.sessions().retrieve(&session_id).await?;
println!(
"{:?} {:?} {:?}",
session.status, session.release_reason, session.signals
);released user_requested [ 'bot_detection_triggered', 'captcha_encountered' ]released user_requested ['bot_detection_triggered', 'captcha_encountered']released user_requested [bot_detection_triggered captcha_encountered]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. |
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 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. Signals reference 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:
console.log(session.sessionViewerUrl);print(session.session_viewer_url)fmt.Println(session.SessionViewerURL)println!("{}", session.session_viewer_url);https://app.steel.dev/sessions/4d7512b8-4dc9-4058-917f-d984ac3473c6The 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.
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.
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));
}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)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))
}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:
{
"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 and 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.
- A block, a CAPTCHA or a bot check: Get past bot detection.
- A proxy that failed: Proxies.
- A session that ran out of time: Set timeouts.
- A login that the site did not accept: Stay signed in across sessions.
- A live view or a recording that does not show: Live view and 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 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, and check that the agent gets past the step where the old run failed.