Logs & Debugging

Logs & Debugging

Inspect what your agent did at every step using the built-in log viewer and trace explorer.

Viewing Logs

Run agent logs <run-id> to view the full log output for a specific run. Use --follow to stream logs in real time for a running agent.

Traces

Run agent trace <run-id> to view a structured breakdown of each step: model calls, tool invocations, inputs, and outputs with timing data.

Debug Mode

Set the --debug flag on any command to enable verbose output including raw HTTP requests, token usage per step, and internal decision logs.

Viewing run logs

queue logs <run-id>

Shows the full log output for a completed run: every reasoning step, tool call, tool result, and the final output. Use --follow to stream logs in real time for an in-progress run.

Run traces

queue trace <run-id>

A trace is a structured breakdown of a run. It shows each step with: model call latency, token usage, the full prompt sent to the model, the model’s response, and tool call details (name, input, output, execution time).

Traces are the primary debugging tool for Queue agents. When an agent does something unexpected, the trace almost always reveals why.

Filtering logs

queue logs --agent refactor-agent --since 24h --status failed

Filter by agent name, time range, and run status. Use --json to pipe structured log data into your own tools.

Debug mode

queue run my-agent “…” --debug

Debug mode prints verbose output during the run itself: the raw prompt sent to the model at each step, full tool inputs and outputs (not truncated), and internal Queue runtime events.

Common failure patterns

max_steps_reached

The agent hit the step limit before finishing. Look at the trace to see where it got stuck. Common cause: the goal was too broad, or the agent got into a loop trying to fix a tool error.

tool_error

A tool failed repeatedly. Check the tool result in the trace for the underlying error message. Common cause: a permissions issue, a malformed input, or a flaky external service.

context_overflow

The run exceeded the model’s context limit even after compression. Reduce the scope of the task, inject less context, or increase context compression aggressiveness in your config.