Errors and logging

Gwenflow separates errors the model can recover from, which are reported back to it, from errors that stop your code.

Handed back to the model

These never raise; the model reads them and adapts:

Situation	What the model gets
A tool raises (after its retries)	`Error executing tool '<name>': <message>` as the tool result
A tool’s arguments are not valid JSON	an error as the tool result
A structured answer does not validate	the validation errors, up to three retries. See Structured output.
A team member or sub-agent hits `max_turns`, a timeout or needs an approval it cannot get	`[handoff failed] ...` or `[sub-agent failed] ...`
A tool call is denied	”The user denied this tool call.”, or your `ToolDenied` reason

A failing summarizer does not fail the run either: the sliding window takes over for that compaction.

Reported in the response

`finish_reason`	Meaning
`stop`	the model answered
`max_turns`	the run used `max_turns` model calls without a final answer; `content` is `None`
`approval_required`	the run is waiting for decisions on `pending_approvals`
`interrupted`	a stream was closed or cancelled before the end

Check it before using content, and check parsed for None when you asked for a structured answer.

Raised

Exception	When
`RuntimeError("Error in calling <provider> API: ...")`	the provider call failed after the SDK’s own retries (network, authentication, rate limit, invalid request); the original error is the `__cause__`
`ValueError`	a missing API key, an unknown provider or tool name in `make_llm` / `make_tools`, or `run()` without input when nothing waits for approval
`FlowError`	an invalid flow: a cycle, duplicate node names, a connection to an unknown node
`FlowNodeError` (a `FlowError`)	a flow node failed after its retries; `.node` is its name
`GwenflowDurabilityError` (a `RuntimeError`)	a durable agent uses a feature durability does not support yet
`RuntimeError`	`run()` or a stream inside a Temporal workflow, or an agent without durability there
`MemoryConflictError`, `MemoryPathError`	long-term memory: a concurrent write, a path outside `/memories`

GwenflowException is the base class of the library’s own exceptions (gwenflow.exceptions).

from gwenflow.flows import FlowError

try:
    response = agent.run(question)
except RuntimeError as e:
    log.error("model call failed: %s", e.__cause__ or e)
    raise

if response.finish_reason == "max_turns":
    ...

Logging

Gwenflow logs through the standard logging module, under the logger gwenlake.gwenflow: tool calls and their errors, sub-agents, compactions, flow nodes, retries.

from gwenflow import set_log_level_to_debug

set_log_level_to_debug()

or with the standard API: logging.getLogger("gwenlake.gwenflow").setLevel(logging.DEBUG). For production, prefer telemetry: every model call, tool call and flow node becomes a span with its inputs, outputs, status and timing.

Get started

Concepts

Models

Agents

Multi-agent

Extend

Memory

Flows

Knowledge

Production

Project

Errors and logging

Handed back to the model

Reported in the response

Raised

Logging

​Handed back to the model

​Reported in the response

​Raised

​Logging

Handed back to the model

Reported in the response

Raised

Logging