zed-industries/zed · error

Schema cannot be made compatible because it contains "{key}"

Error message

Schema cannot be made compatible because it contains "{key}"

What it means

Raised while adapting a tool's JSON schema to the subset providers accept: the schema contains construct "{key}" that cannot be translated (an unresolvable or unsupported $ref form or equivalent), so making it compatible would require rewriting semantics the adapter doesn't support. Per the adapter's contract the schema is left untouched rather than half-rewritten, and the caller receives this error; typically the tool's schema generator (e.g. pydantic or zod-to-json-schema) emitted a reference format outside `#/$defs/<name>` and `#/definitions/<name>`.

Source

Thrown at crates/language_model_core/src/tool_schema.rs:208

/// definition was looked up under, and `name` is the definition name.
fn parse_ref(ref_str: &str) -> Result<(&'static str, &str)> {
    if let Some(name) = ref_str.strip_prefix("#/$defs/") {
        return Ok(("$defs", name));
    }
    if let Some(name) = ref_str.strip_prefix("#/definitions/") {
        return Ok(("definitions", name));
    }
    anyhow::bail!(
        "Unsupported $ref format (only `#/$defs/<name>` and `#/definitions/<name>` are supported): {ref_str}"
    );
}

fn adapt_to_json_schema_subset(json: &mut Value) -> Result<()> {
    if let Value::Object(obj) = json {
        const UNSUPPORTED_KEYS: [&str; 4] = ["if", "then", "else", "$ref"];

        for key in UNSUPPORTED_KEYS {
            anyhow::ensure!(
                !obj.contains_key(key),
                "Schema cannot be made compatible because it contains \"{key}\""
            );
        }

        const KEYS_TO_REMOVE: [(&str, fn(&Value) -> bool); 6] = [
            ("format", |value| value.is_string()),
            ("additionalProperties", |_| true),
            ("propertyNames", |_| true),
            ("exclusiveMinimum", |value| value.is_number()),
            ("exclusiveMaximum", |value| value.is_number()),
            ("optional", |value| value.is_boolean()),
        ];
        for (key, predicate) in KEYS_TO_REMOVE {
            if let Some(value) = obj.get(key)
                && predicate(value)
            {
                obj.remove(key);

View on GitHub (pinned to f4178619ac)

Solutions

1. Change the tool's schema generator settings so references are inlined (e.g. schemars inline_subschemas) instead of emitted
2. Ensure $ref values use `#/$defs/<name>` or `#/definitions/<name>` forms only
3. Remove exotic JSON Schema keywords the provider subset doesn't support from the tool definition
4. On this error, send the schema unchanged and let the provider report the specific incompatibility

When it happens

Trigger: Thrown at crates/language_model_core/src/tool_schema.rs:208 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of zed-industries/zed@f4178619ac (2026-08-20). Data as JSON: /api/errors/3271d4d102d97c4b. Report an issue: GitHub.