STITCH_CIRCUIT_OPEN
The circuit breaker is open after repeated failures and short-circuited the call.
What you'll see
A stitch configured with a circuit
fails immediately — no request leaves the process — with a StitchError,
surfaced on the event stream as an error event. The dependency itself isn't
being hit: the breaker tripped open after repeated failures and is now
fast-failing every call to protect it. This is the breaker doing its job, not a
fresh failure.
STITCH_CIRCUIT_OPEN is this page's catalog ID, not a
runtime value — the thrown error has no .code. Recognise a short-circuit
by its fields instead: status === 503 with attempts === 0, the
combination that means the breaker answered before any request was made (the
message is circuit open). See telling failures
apart.
Why it happens
The breaker counts consecutive failures. Once it reaches failures,
it trips open and records the moment. While open, every call fast-fails for
cooldown instead of touching the dependency. Seeing this error means you are
inside that cooldown window — the breaker hasn't yet allowed the half-open
trial that decides whether to close again. The real failures that tripped it
happened on earlier calls; this one is just being short-circuited.
How to fix
Most of the time this is working as intended — a failing dependency is being shielded from a stampede. Work through these in order:
- Wait it out. After
cooldownthe breaker goes half-open and lets a single trial through; a success closes it and traffic resumes. If the dependency has recovered, the next call after the window will succeed. - Fix the underlying dependency. The breaker is a symptom, not the cause. Find
and fix the real failures — the earlier errors that incremented the count to
failures— so the half-open trial can close it. - Tune the thresholds. Raise
failuresif the breaker trips on transient blips; adjustcooldownto control how long it fast-fails before retesting. - Check the
key. Breakers are keyed (default: the stitch/host key). If two unrelated stitches share akey, one failing dependency trips the breaker for both — give them distinct keys so they don't share a breaker.
Pair the breaker with retry and timeout: timeouts and retries absorb the transient failures, and the breaker steps in only once those keep failing.
Stuck, or debugging with an agent? Ask the docs
MCP — search_docs('STITCH_CIRCUIT_OPEN')
pulls this page and the related guides straight into context.