Guide

4 min read

What to do when the gate blocks

The gate returned ERR. Here is what that means and what your options are.

What ERR means

An ERR verdict means StateAnchor detected a breaking API change in at least one of the four drift syndromes. The change would break consumers that depend on the current contract if it reached production.

See Gate Engine for how the four syndromes (parent, merge-base, LKG, deployed) work, Gate Classification for the classification rules, and Gate Kinds Reference for all 33 kinds with YAML examples.

ERR, WARN, and INFO lanes

Not every gate finding blocks automatically. StateAnchor classifies each change into one of three lanes:

• ERR -- always blocks. Requires either a code fix (reverse the breaking change) or a filed exception before the PR can merge. See the Gate Kinds Reference for the full list of ERR kinds.
• WARN -- threshold-based. By default the gate proceeds on WARN findings; set a positive warn_count_threshold in stateanchor.yaml to block once the WARN count reaches it.
• INFO -- never blocks. Additive changes and description-only changes are recorded for visibility but do not affect the gate decision.

If you see optional_field_removed (WARN), the removed field was not marked required -- callers that never sent it are unaffected. Consider whether any callers actually depend on sending this field before treating it as blocking. Compare this to field_removed (ERR), which fires on required-field removal and always requires a fix or an exception.

Your options

Option 1 — Fix the change (recommended)

The most common case: the breaking change was unintentional.

• Review the gate verdict comment on your PR for the specific ERR classification.
• Look at the changed endpoint or field.
• Reverse or adjust the change so the contract is preserved.
• Push the fix — the gate reruns automatically.

For a worked example of how to restructure a removal into an additive deprecation, see Handling a breaking change.

Option 2 — Create an exception (intentional breaking change)

If the breaking change is intentional and approved, file a drift exception. An exception suppresses a specific finding for a bounded time window.

• Open your project in the StateAnchor dashboard → Exceptions → New exception.
• Select the affected change kind and endpoint.
• Provide a justification (visible to your team) and an approver.
• The exception starts in ANERGIC state and activates only after a second independent signal (code owner acknowledgement, consumer test, or manual confirmation). This two-signal requirement prevents unreviewed exceptions from suppressing the gate silently.
• The exception expires automatically (90-day maximum TTL). When it expires, the finding re-activates and the gate may block again on the next push.

See Drift exceptions for the full ANERGIC → ACTIVE → EXPIRED state machine and the second-signal flow.

Via stateanchor.yaml (coming soon):

exceptions:
  - change_type: endpoint_removed
    endpoint: /users/{id}
    reason: "Deprecated endpoint removed per v2 migration plan"
    expires: 2026-07-01

Option 3 — Investigate the classification

If you believe the gate classification is wrong:

• Use the share link from the gate result to open the full verdict panel.
• Review which syndrome triggered the ERR and the exact change kind.
• If it looks like a false positive, open an issue at github.com/stateanchor-hq/stateanchor with the share link attached.

Understanding the share link

Every gate result has a shareable link. Click Copy share link on the run detail view. The share page shows the gate verdict, syndrome breakdown, and per-change classifications — no StateAnchor account required to view. Share it with your team to discuss the verdict without everyone needing access.

Turning off enforcement temporarily

If you need to merge urgently and will fix the drift separately:

• Switch your project to observe mode in the StateAnchor dashboard → Settings → Gate mode: Observe.
• The gate still runs and reports (PR comments, dashboard verdicts) — it just does not block the merge.
• Switch back to enforce mode before your next sprint. Drift accumulates silently when the gate is non-blocking.

Related

• Drift exceptions -- how to suppress a finding for an intentional breaking change
• Gate kinds reference -- the exact change kinds that land in ERR
• Gate engine -- how the four syndromes produce verdicts