Skip to main content

​
Promotion gate blocked a version (PROMOTION_GATE_FAILED / RED_TEAM_GATE_FAILED)

Promoting an agent version 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