BigPizzaV3/CodexPlusPlus · error

Unsupported native runtime component

Error message

Unsupported native runtime component: {file}

What it means

Before patching, prepare() verifies every file listed in the RuntimeContract by comparing its SHA-256 against the expected hash. If any component's hash differs, the runtime does not match the known-good build Codex++ supports (wrong version, corrupted download, or previously modified file), and patching is refused, naming the offending file.

Solutions

  1. Delete the affected runtime directory under the runtime root and let Codex++/the plugin re-download it so hashes match the contract
  2. Reinstall the plugin at the version matching the current RuntimeContract (or upgrade Codex++ so its contract matches the new runtime)
  3. Verify no antivirus/sync tool is modifying files in the runtime cache and restore from a clean source
Defensive patterns

Strategy: retry

Validate before calling

for (file, expected) in &contract.files {
    let actual = sha(&read_regular(&runtime.join(file), 128 * 1024 * 1024)?);
    if actual != *expected { eprintln!("runtime file {file} hash mismatch; reinstall needed"); }
}

Try / catch

if let Err(e) = prepare(&paths, &key, &contract) {
    if e.to_string().starts_with("Unsupported native runtime component") {
        remove_runtime_dir(&runtime)?;      // delete the corrupt/mismatched runtime
        redownload_runtime(&key)?;          // let the plugin re-fetch it
        prepare(&paths, &key, &contract)?;
    }
}

Prevention

When it happens

Trigger: prepare() (via reconcile_locked) hashes runtime_root/<key>/<file> for each (file, expected) in contract.files and the digest mismatches — e.g. the plugin auto-updated the runtime underneath Codex++, a download was truncated, or an external tool modified a runtime binary.

Common situations: Plugin runtime upgrades that outpace the pinned contract; antivirus quarantining/altering files; interrupted downloads leaving corrupt node_modules; manual edits inside the runtime cache.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

AI-assisted analysis of BigPizzaV3/CodexPlusPlus@b1ed92e5e4 (2026-09-19). Data as JSON: /api/errors/f732775ba590d087. Report an issue: GitHub.

Appendix: source

Thrown at crates/codex-plus-core/src/native_browser.rs:373

            continue;
        }
        let data: Value = serde_json::from_slice(&read_regular(&descriptor, 1024 * 1024)?)?;
        keys.insert(selected_key(&data, &paths.runtime_root)?);
    }
    ensure!(
        keys.len() <= 1,
        "Ambiguous runtime selection; no cache was modified"
    );
    Ok(keys.into_iter().next())
}

fn prepare(paths: &BrowserPaths, key: &str, contract: &RuntimeContract) -> Result<()> {
    ensure!(key_valid(key), "Invalid runtime key");
    let runtime = paths.runtime_root.join(key);
    let target = runtime.join(SERVICE);
    let _runtime_guards = pin_parents(&target)?;
    for (file, expected) in &contract.files {
        ensure!(
            sha(&read_regular(&runtime.join(file), 128 * 1024 * 1024)?) == *expected,
            "Unsupported native runtime component: {file}"
        );
    }
    let mut current = read_regular(&target, MAX_SERVICE)?;
    let backup_dir = paths.state_root.join(key);
    plain_path(&backup_dir)?;
    fs::create_dir_all(&backup_dir)?;
    let _backup_guards = pin_parents(&backup_dir.join("journal.json"))?;
    let backup = backup_dir.join("original.mjs");
    let journal_path = backup_dir.join("journal.json");
    let control = paths.state_root.join("control.json");
    if journal_path.exists() {
        let (journal, original, recorded_candidate) = recovery_material(paths, key, contract)?;
        let candidate = transform(&original, &control, contract)?;
        if current == recorded_candidate {
            if candidate == recorded_candidate {
                return Ok(());

View on GitHub (pinned to b1ed92e5e4)