> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Promotion gate blocked a version (PROMOTION_GATE_FAILED / RED_TEAM_GATE_FAILED)

> Resolve the structured gate blocks on version promotion — PROMOTION_GATE_FAILED (pinned eval suite regressed) and RED_TEAM_GATE_FAILED (safety baseline or floor breached). Decode the gate report, fix the failing golden sets or red-team categories, and re-promote.

# Promotion gate blocked a version (PROMOTION\_GATE\_FAILED / RED\_TEAM\_GATE\_FAILED)

Promoting an [agent version](/agents/agent-versions) can return a 422 with one
of two structured error codes when that agent has change-control gates
configured:

* `PROMOTION_GATE_FAILED` — the pinned eval suite (your golden sets) regressed
  on the candidate version, or a set could not run at all.
* `RED_TEAM_GATE_FAILED` — the candidate fell below the configured safety
  floor, or newly compromised one or more adversarial probes the pinned
  baseline had resisted.

Both are deliberate fail-closed gates: the promote is refused and the live
agent keeps serving the previous version until you resolve the regression.
The response body carries the full gate report, and every block lands in the
org audit log, so nothing about the attempt is lost.

## 1. Find where the gate is configured

Either gate is set per agent, and any authenticated caller can read it.

* Promotion (eval) gate: `GET /agents/:id/promotion-gate/settings` /
  `PUT /agents/:id/promotion-gate/settings` (owner/admin to change). Fields:
  `enabled`, `golden_set_ids`, `p95_regression_threshold`,
  `judge_score_regression_threshold`, `min_pass_rate`.
* Red-team gate: `GET /agents/:id/red-team/gate-settings` /
  `PUT /agents/:id/red-team/gate-settings` (owner/admin to change). Fields:
  `enabled`, `min_safety_score`.

In the dashboard, the same settings live under
**Agents → \[agent] → Versions → Promotion gate**.

The gate config is stored on your organization settings, not on a version, so
a rollback or a promote never resets it.

## 2. Decode the block message

### PROMOTION\_GATE\_FAILED

The 422 response includes a `gate_report` with four fields to check:

* `gate_report.reasons[]`
  * `regression_detected` — the pooled pass rate or latency regressed past
    your thresholds versus the prior run.
  * `pass_rate_below_minimum` — the aggregate pass rate is below
    `min_pass_rate`, or no cases produced a measurement.
  * `eval_sets_failed_to_run` — one or more pinned golden sets could not run,
    so the gate cannot certify the candidate (fail closed).
  * `gate_execution_error` — the suite itself errored; the gate is blocked
    rather than skipped.
* `gate_report.golden_set_ids[]` — which pinned sets were scored.
* `gate_report.aggregate.pass_rate` and
  `gate_report.aggregate.has_regression` — the numbers that tripped the gate.
* `gate_report.thresholds` — the thresholds the decision was made against, so
  you can see exactly which limit was exceeded.

### RED\_TEAM\_GATE\_FAILED

The 422 response includes a `red_team_gate_report`:

* `red_team_gate_report.reasons[]`
  * `safety_score_below_minimum` — the overall safety score is under
    `min_safety_score`. This bites on the first run too — no baseline is
    required.
  * `safety_regression_vs_baseline` — at least one probe the pinned baseline
    had resisted came back compromised.
  * `red_team_execution_error` — the pack could not run; fail closed again.
* `red_team_gate_report.scorecard.overall.grade` and
  `red_team_gate_report.scorecard.overall.safetyScore` — the verdict.
* `red_team_gate_report.scorecard.failures[]` — the compromised probes, each
  with a `category`: one of `jailbreak`, `prompt_injection`,
  `data_exfiltration`, `policy_guardrail`.

The dashboard promotion-gate panel surfaces the same explanation inline when
you promote from the Versions screen.

## 3. Recover and re-promote

### For PROMOTION\_GATE\_FAILED

1. Read the gate report and identify which golden sets regressed.
2. Fix the prompt drift, or — if the new behaviour is intentional — adjust the
   gate: lower `min_pass_rate`, widen the regression thresholds, or drop the
   set that is no longer relevant via
   `PUT /agents/:id/promotion-gate/settings`.
3. Re-run the eval suite against the candidate version.
4. Promote again.

### For RED\_TEAM\_GATE\_FAILED

1. Read the failures and note which categories broke.
2. Either harden the prompt against that category, or intentionally raise the
   floor (`min_safety_score`) /
   re-pin the baseline when the new risk tradeoff is accepted by your team.
   Re-running `POST /agents/:id/red-team/run` with a `categories` filter lets
   you isolate the failing category before promoting again.
3. Promote again — the gate re-scores the candidate on each promote attempt.

In both cases the gate has already written the block to the audit log, so the
recovery path above is also your evidence trail for why a version was not
shipped.

## 4. If you do not want a gate

Set `enabled: false` on the relevant gate settings (owner/admin). With no gate
configured, promotion skips the check entirely — that is the same "not
configured" state every agent starts in.

## See also

* [Troubleshooting: agent eval-queue failures](/troubleshooting/agent-eval-queue) —
  when the eval run itself is what is stuck.
* [Troubleshooting: prompt-regression rejects an agent-version rollback](/troubleshooting/agent-prompt-regression-registered) —
  the sibling gate on the rollback path.
* [Safely roll out an AI agent](/guides/ai-agent-rollout-pipeline#troubleshooting) —
  the pipeline whose stage gates these protect.
* [Agent versions](/agents/agent-versions) — the version lifecycle being
  promoted.