codex doctor assertion failed: - {} next: run `f codex enabl

Error message

codex doctor assertion failed:
- {}
next: run `f codex enable-global --full`, then exercise `f codex open ...` or `f ai codex new` through Flow until outcomes appear

What it means

The `codex doctor` command runs a set of assertions about the local Codex integration (global install/enablement, daemon state, etc.) and aggregates failures. If any assertion fails, it bails with a formatted report of the failed checks plus a suggested remediation workflow: fully enabling Codex globally and exercising `f codex open ...` or `f ai codex new` through Flow until outcome records appear.

Source

Thrown at src/ai.rs:8909

        if snapshot.skill_eval_events_on_disk == 0 {
            failures.push("no Codex route events recorded yet".to_string());
        }
        if snapshot.skill_scorecard_entries == 0 {
            failures.push("no skill scorecard entries built yet".to_string());
        }
        if snapshot.skill_eval_outcomes_on_disk == 0 {
            failures.push(
                "no grounded skill outcome events recorded yet; the system is still affinity-only"
                    .to_string(),
            );
        }
    }

    if failures.is_empty() {
        return Ok(());
    }

    bail!(
        "codex doctor assertion failed:\n- {}\nnext: run `f codex enable-global --full`, then exercise `f codex open ...` or `f ai codex new` through Flow until outcomes appear",
        failures.join("\n- ")
    )
}

fn codex_daemon_env_usize(primary: &str, legacy: &str) -> Option<usize> {
    std::env::var(primary)
        .ok()
        .or_else(|| std::env::var(legacy).ok())
        .and_then(|value| value.parse::<usize>().ok())
}

fn codex_daemon_env_u64(primary: &str, legacy: &str) -> Option<u64> {
    std::env::var(primary)
        .ok()
        .or_else(|| std::env::var(legacy).ok())
        .and_then(|value| value.parse::<u64>().ok())
}

View on GitHub (pinned to a747e741ae)

Solutions

Run `f codex enable-global --full` to fully enable the Codex integration
Exercise the integration: `f codex open ...` or `f ai codex new` so outcome records are produced
Re-run `f codex doctor` to confirm all assertions pass
If checks still fail, inspect daemon environment settings (ports, timeouts) and ensure the Codex daemon is running

Example fix

// before
$ f codex doctor
error: codex doctor assertion failed:
- no codex outcomes recorded
// after
$ f codex enable-global --full
$ f codex open .
$ f codex doctor
ok

Defensive patterns

Strategy: validation

Validate before calling

// Shell: pre-check before relying on doctor passing
f codex doctor || { f codex enable-global --full; f codex open .; f codex doctor; }

Type guard

fn codex_ready(doctor_output: &str) -> bool {
    !doctor_output.contains("assertion failed")
}

Try / catch

match codex_doctor() {
    Ok(()) => (),
    Err(e) if e.to_string().starts_with("codex doctor assertion failed") => {
        let report = e.to_string();
        eprintln!("{report}");
        eprintln!("Remediation: f codex enable-global --full, then f codex open ...");
    }
    Err(e) => return Err(e),
}

Prevention

Run `f codex enable-global --full` during machine setup before using Codex features
Exercise `f codex open ...` / `f ai codex new` at least once so outcome records exist
Run `f codex doctor` as part of your environment sanity checks, not as a first-time setup step

When it happens

Trigger: Running `f codex doctor` when one or more checks fail — e.g. Codex global config not fully enabled, daemon not reachable or misconfigured, or no recorded Codex outcomes because the integration has never been exercised.

Common situations: Fresh machine setup where `f codex enable-global` was never run or was run without `--full`; daemon env values (ports/timeouts) misconfigured; a user runs doctor before ever opening a Codex session so no outcomes exist yet.

Related errors

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