nikivdev/code · error

unsupported external CLI link record version {} in {}

Error message

unsupported external CLI link record version {} in {}

What it means

`read_link_record` parses a link record TOML file and validates its `version` field against the library's supported `LINK_RECORD_VERSION`. A record written by a different (older or newer) version of the tooling is rejected, with the found version and file path in the message.

Source

Thrown at src/external_cli.rs:524

        if !path.is_dir() {
            continue;
        }
        let manifest = path.join(MANIFEST_NAME);
        if manifest.is_file() {
            manifests.push(manifest);
        }
    }

    manifests
}

fn read_link_record(path: &Path) -> Result<ExternalCliLinkRecord> {
    let content =
        fs::read_to_string(path).with_context(|| format!("failed to read {}", path.display()))?;
    let record: ExternalCliLinkRecord =
        toml::from_str(&content).with_context(|| format!("failed to parse {}", path.display()))?;
    if record.version != LINK_RECORD_VERSION {
        bail!(
            "unsupported external CLI link record version {} in {}",
            record.version,
            path.display()
        );
    }
    Ok(record)
}

fn read_manifest(path: &Path) -> Result<ExternalCliManifest> {
    let content =
        fs::read_to_string(path).with_context(|| format!("failed to read {}", path.display()))?;
    let manifest: ExternalCliManifest =
        toml::from_str(&content).with_context(|| format!("failed to parse {}", path.display()))?;
    if manifest.version != 1 {
        bail!(
            "unsupported external CLI manifest version {} in {}",
            manifest.version,
            path.display()

View on GitHub (pinned to a747e741ae)

Solutions

1. Re-create the links with the current version of the tooling so records are written with `LINK_RECORD_VERSION`.
2. Hand-edit the record's `version` field to the supported value only if the rest of the schema matches the current format.
3. Upgrade (or pin) the toolchain so the record version and the library agree.
4. Delete stale records and re-link affected tools.

Example fix

# before (link record)
version = 1

# after (supported LINK_RECORD_VERSION)
version = 2

fn check_record_version(path: &Path, supported: i64) -> Result<(), String> {
    let text = std::fs::read_to_string(path).map_err(|e| e.to_string())?;
    let v: toml::Value = toml::from_str(&text).map_err(|e| e.to_string())?;
    let ver = v.get("version").and_then(|v| v.as_integer()).unwrap_or(-1);
    if ver == supported { Ok(()) } else { Err(format!("{}: version {ver} != {supported}", path.display())) }
}

match loader.load_link_records(&dir) {
    Err(e) if e.to_string().contains("unsupported external CLI link record version") => {
        eprintln!("{e}; regenerating links with current tooling");
        regen_all_links()?;
        loader.load_link_records(&dir)
    }
    other => other,
}

When it happens

Trigger: Calling `install_external_cli_link`, `resolve_installed_external_cli_tool`, or `load_link_records` on a link record file whose parsed `version` differs from `LINK_RECORD_VERSION`.

Common situations: Link records created by an older release of the toolchain after an upgrade; records hand-written or copied from a different project using a different record format; a partially migrated workspace mixing record versions.

Related errors

• external CLI link {} points to manifest with mismatched id {
• unsupported external CLI manifest version {} in {}
• {} has no exec.run argv in {}
• {} has no exec.run program in {}
• external CLI {} exited unsuccessfully with status {}

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