external CLI link {} points to manifest with mismatched id {

Error message

external CLI link {} points to manifest with mismatched id {}

What it means

`resolved_from_link_record` validates that a link record still agrees with the manifest it points to. If the manifest at `record.manifest_path` declares a different `id` than the record's `id`, the link is stale or corrupt and the error reports both ids.

Source

Thrown at src/external_cli.rs:406

                .map(|tool| tool.manifest_path.display().to_string())
                .collect::<Vec<_>>()
                .join(", ");
            bail!(
                "multiple external CLI manifests matched {}: {}",
                id,
                locations
            )
        }
    }
}

fn resolved_from_link_record(
    record: &ExternalCliLinkRecord,
    registration_path: Option<PathBuf>,
) -> Result<ResolvedExternalCliTool> {
    let manifest = read_manifest(&record.manifest_path)?;
    if manifest.id != record.id {
        bail!(
            "external CLI link {} points to manifest with mismatched id {}",
            record.id,
            manifest.id
        );
    }
    resolved_from_manifest(
        record.manifest_path.clone(),
        manifest,
        ExternalCliResolutionKind::InstalledLink,
        registration_path,
    )
}

fn resolved_from_manifest(
    manifest_path: PathBuf,
    manifest: ExternalCliManifest,
    resolution: ExternalCliResolutionKind,
    registration_path: Option<PathBuf>,

View on GitHub (pinned to a747e741ae)

Solutions

Re-create the link (re-run the install/link flow) so the record and manifest ids match again.
Edit the link record's `id` to match the manifest's current `id` if the rename was intentional.
Point the link record's `manifest_path` at the correct manifest for the recorded id.
Verify the manifest file at the recorded path wasn't overwritten by another tool.

Example fix

# before (link record)
id = "old-name"
manifest_path = "/tools/new-name/tool.toml"

# after
id = "new-name"
manifest_path = "/tools/new-name/tool.toml"

Defensive patterns

Strategy: validation

Validate before calling

fn check_link_record(record: &ExternalCliLinkRecord) -> Result<(), String> {
    let manifest = read_manifest(&record.manifest_path)
        .map_err(|e| format!("link target unreadable: {e}"))?;
    if manifest.id != record.id {
        return Err(format!("link id {} != manifest id {}", record.id, manifest.id));
    }
    Ok(())
}

Try / catch

match resolver.resolve_installed_external_cli_tool(&link_path) {
    Err(e) if e.to_string().contains("mismatched id") => {
        eprintln!("stale link detected; re-linking...");
        installer.install_external_cli_link(&source)?;
        resolver.resolve_installed_external_cli_tool(&link_path)
    }
    other => other,
}

Prevention

Never hand-edit link records or manifests' `id` after linking.
Re-run the link flow whenever a manifest id changes.
Treat link records as generated artifacts (gitignore or regenerate them).
Periodically validate all link records against their manifests.

When it happens

Trigger: Calling `resolve_installed_external_cli_tool`, `list_external_cli_tools`, or `install_external_cli_link` where a link record file references a manifest whose `id` field no longer matches `record.id` — typically because the manifest was edited, moved, or replaced after the link was created.

Common situations: The manifest at the target path was updated with a new id; a symlink now points at a different tool's manifest; the link record was hand-edited or copied from another tool.

Related errors

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