What causes "Quality gate blocked commit" in nikivdev/code?

Fix the issues listed above the error in the output.

Quality gate blocked commit

Error message

Quality gate blocked commit

What it means

The commit command runs quality gates before committing; when gate mode is "block" and issues were found, it restores the staged snapshot and aborts the commit with this error. It exists to stop low-quality changes from entering history while pointing the user at the reported issues and the override flag.

Source

Thrown at src/commit.rs:4232

        let mut gate_failures: Vec<String> = quality.gate_failures.clone();
        if gate_overrides.skip_docs {
            gate_failures.retain(|failure| !is_doc_gate_failure(failure));
        }
        if gate_overrides.skip_tests {
            gate_failures.retain(|failure| !is_test_gate_failure(failure));
        }

        if !gate_failures.is_empty() && mode != "off" {
            println!();
            for failure in &gate_failures {
                eprintln!("  quality: {}", failure);
            }

            if mode == "block" {
                eprintln!("\nCommit blocked by quality gates.");
                eprintln!("Fix the issues above, or override with: f commit --skip-quality");
                restore_staged_snapshot_in(&repo_root, &staged_snapshot)?;
                bail!("Quality gate blocked commit");
            } else {
                eprintln!("\nQuality warnings above. Proceeding with commit.");
            }
        }

        // Auto-generate/update feature docs if enabled
        let auto_docs = quality_config.auto_generate_docs.unwrap_or(true);
        if auto_docs && mode != "off" && !gate_overrides.skip_docs {
            let commit_sha_preview = git_capture_in(&repo_root, &["rev-parse", "--short", "HEAD"])
                .unwrap_or_else(|_| "unknown".to_string())
                .trim()
                .to_string();

            match features::apply_quality_results(&repo_root, quality, &commit_sha_preview) {
                Ok(actions) => {
                    for action in &actions {
                        println!("  feature docs: {}", action);
                    }

View on GitHub (pinned to a747e741ae)

Solutions

Fix the issues listed above the error in the output.
If the issues are acceptable, re-run with `f commit --skip-quality` to override the gate.
Switch gate mode from "block" to "warn" in quality config if warnings should not block.
Commit in a clean state after re-running formatters/linters locally.

Example fix

// before
f commit
// error: Quality gate blocked commit
// after (intentional override)
f commit --skip-quality

Defensive patterns

Strategy: validation

Validate before calling

// run the same gates locally before committing
// e.g. `cargo fmt --check && cargo clippy -- -D warnings && cargo test`

Try / catch

if let Err(e) = commit_cmd.run() {
    if e.to_string().contains("Quality gate blocked commit") {
        eprintln!("Fix reported issues, or re-run with: f commit --skip-quality");
    }
}

Prevention

Run linters/formatters in a pre-commit hook so gates never surprise you.
Keep quality gate config in the repo and update code when rules change.
Use --skip-quality only deliberately, never as a habit.

When it happens

Trigger: Running `f commit` with quality gates configured in block mode when the staged changes violate one or more gates (lint/format/complexity/test issues printed just above the error).

Common situations: Failing linters or formatters on staged code; quality score below threshold; new gate rules added by a config/version update that existing code violates.

Related errors

AI-assisted analysis of nikivdev/code@a747e741ae (2026-09-01). Data as JSON: /api/errors/fdbcb00216aedc28. Report an issue: GitHub.