The host (v{}) and guest (v{}) are using incompatible versio

Error message

The host (v{}) and guest (v{}) are using incompatible versions of Zed. The peer with the older version must update to collaborate.

What it means

Thrown by the join_project handler when the feature set the guest reports in JoinProject differs from the host's registered feature set (compared as HashSets). The message interpolates both peers' zed versions from the connection pool when available ('unknown' otherwise). Feature-set equality is the protocol-compatibility proxy: mismatched features mean the collaboration protocol versions cannot talk.

Source

Thrown at crates/collab/src/rpc.rs:1991

    tracing::info!(%project_id, "join project");

    let db = session.db().await;
    let project_model = db.get_project(project_id).await?;
    let host_features: Vec<String> =
        serde_json::from_str(&project_model.features).unwrap_or_default();
    let guest_features: HashSet<_> = request.features.iter().collect();
    let host_features_set: HashSet<_> = host_features.iter().collect();
    if guest_features != host_features_set {
        let host_connection_id = project_model.host_connection()?;
        let mut pool = session.connection_pool().await;
        let host_version = pool
            .connection(host_connection_id)
            .map(|c| c.zed_version.to_string());
        let guest_version = pool
            .connection(session.connection_id)
            .map(|c| c.zed_version.to_string());
        drop(pool);
        Err(anyhow!(
            "The host (v{}) and guest (v{}) are using incompatible versions of Zed. The peer with the older version must update to collaborate.",
            host_version.as_deref().unwrap_or("unknown"),
            guest_version.as_deref().unwrap_or("unknown"),
        ))?;
    }

    let (project, replica_id) = &mut *db
        .join_project(
            project_id,
            session.connection_id,
            session.user_id(),
            request.committer_name.clone(),
            request.committer_email.clone(),
        )
        .await?;
    drop(db);

    tracing::info!(%project_id, "join remote project");

View on GitHub (pinned to bc538def45)

Solutions

Update Zed on the peer reported as older (or both) so the feature sets match, then re-share and re-join
Re-establish the connection (reconnect both clients) so fresh version/features are registered before retrying the join
If operating a fleet, pin peers to the same release to avoid mid-session drift

Example fix

// before
let joined = guest_client.join_project(project_id, my_features.clone()).await?;

// after (pre-check versions, fail fast with a clear message)
if let Some(host_version) = host_advertised_version {
    if host_version != my_version {
        return Err(anyhow!(
            "collab requires the same Zed version (host v{host_version}, you v{my_version}); please update"
        ));
    }
}
let joined = guest_client.join_project(project_id, my_features.clone()).await?;

Defensive patterns

Strategy: validation

Validate before calling

// Compare advertised versions before attempting the join.
if let Some(host_version) = host_advertised_version {
    if host_version != my_zed_version {
        return Err(anyhow!(
            "collab requires matching Zed versions (host v{host_version}, you v{my_zed_version})"
        ));
    }
}
client.join_project(project_id, features).await?;

Type guard

fn features_compatible(guest: &HashSet<String>, host: &HashSet<String>) -> bool {
    guest == host
}

Try / catch

if let Err(err) = client.join_project(project_id, features).await {
    if err.to_string().contains("incompatible versions") {
        self.ui.prompt_update(&err.to_string());
        return Ok(()); // block retry until the client updates
    }
    return Err(err);
}

Prevention

Keep collaborators on the same Zed release; auto-update both peers
Compare versions/features at connection time, before opening a share
Show the embedded version strings from the error to the user so they know which peer must update

When it happens

Trigger: Guest on an older Zed joins a project hosted by a newer Zed (or vice versa) where the collab feature list changed; nightly/stable mix; one peer's client failed to advertise its features in the connection preamble.

Common situations: One collaborator auto-updated while the other is on a pinned/old install; stable and preview channels collaborating; enterprise installs lagging behind; missing zed_version/features during connection registration producing 'unknown'.

Related errors

AI-assisted analysis of zed-industries/zed@bc538def45 (2026-08-16). Data as JSON: /api/errors/22128650b238bd9b. Report an issue: GitHub.