When something fails

Before you start

Work through Default runtime vs live LLM so you have seen both successful default runs and (optionally) live provider setup. Keep the SDK installed per Install and build.

Concept

ArcFlow splits failures into two phases. The phase tells you whether to edit your workflow file or inspect a specific run.

WorkflowConfigurationError means the workflow or agent definition is invalid, or you called APIs in the wrong order. Nothing useful reached the engine, or validation stopped the run before execution began. Examples: empty agent name, no steps registered, empty run input, passing a string to step() instead of an Agent.

WorkflowExecutionError means execution started and a step failed at runtime. The definition was structurally acceptable, but something went wrong inside the engine or provider layer. Examples: live provider HTTP failure after retries, tool execution failure, timeout. Subclasses like RetryExhaustedError and WorkflowTimeoutError add attributes; the base class carries run_id and failed_step when the runtime knows them.

Reading the message: ArcFlow SDK validation uses a two-part sentence:

The [ArcFlow] prefix lets you grep logs. The first clause is the rule you broke. The second clause is the fix. Configuration errors never include a run_id because there is no run to inspect. Execution errors often do; use err.run_id and workflow.trace() after catching them.

For a full exception hierarchy see Python SDK exception reference. This lesson stays with the two types you will see most often in the first week.

Minimal example

Save as failure_modes.py:

from arcflow import Agent, Workflow
from arcflow.exceptions import WorkflowConfigurationError

# Configuration error: invalid agent
try:
 Agent(name="", role="x", instructions="y")
except WorkflowConfigurationError as err:
 print("config (agent):", err)

# Configuration error: no steps
try:
 Workflow("lonely").run("hello")
except WorkflowConfigurationError as err:
 print("config (workflow):", err)

# Success path for contrast
ok = Agent(name="writer", role="write", instructions="Reply briefly.")
wf = Workflow("ok")
wf.step(ok)
result = wf.run("test input")
print("success run_id:", result.run_id)

Run:

python failure_modes.py

You should see two [ArcFlow] configuration messages, then a successful UUID on the last line.

Verify

Spot the phase. For each message you print, ask: "Did a run start?" If no run_id exists and the error mentions must be or Cannot run, it is configuration. Fix the definition and rerun.

Execution error shape (optional read). Live provider failures require a key and network. If you run a workflow with provider=OpenAI(model="gpt-4o") and an invalid key, you may see ProviderExecutionError (a related execution-time type). Inspect:

except ProviderExecutionError as err:
 print(err)
 print(getattr(err, "provider_id", None))

Stub-only workflows in this track rarely raise WorkflowExecutionError unless you add tools, timeouts, or test hooks later.

Trace after execution failure. When WorkflowExecutionError includes run_id, fetch detail:

except WorkflowExecutionError as err:
 print(err.run_id, err.failed_step)
 # after run() on the same workflow instance:
 # trace = workflow.trace()

Message format drill. Pick any WorkflowConfigurationError from this track (empty name, no steps). Confirm both sentences are present: problem, then remediation.

Next steps

You have finished the fundamentals track. Continue with:

Return to the Fundamentals track overview if you want the lesson index.