zed-industries/zed · error

Unexpected JSON code block tag: {label}

Error message

Unexpected JSON code block tag: {label}

What it means

Zed's docs preprocessor rewrites fenced JSON blocks in documentation by their tag label (`"settings"`, `"semantic_token_rules"`, …, then fixes them up and parses with `parse_json_with_comments`); any unrecognized label falls into the catch-all arm and aborts the whole docs build with `Unexpected JSON code block tag: {label}` (main.rs:576).

Source

Thrown at crates/docs_preprocessor/src/main.rs:576

                    snippet_json_fixed.insert(0, '{');
                    snippet_json_fixed.push_str("\n}");
                }

                settings::parse_json_with_comments::<theme::IconThemeFamilyContent>(
                    &snippet_json_fixed,
                )?;
            }
            "semantic_token_rules" => {
                if !snippet_json_fixed.starts_with('[') || !snippet_json_fixed.ends_with(']') {
                    snippet_json_fixed.insert(0, '[');
                    snippet_json_fixed.push_str("\n]");
                }

                settings::parse_json_with_comments::<settings::SemanticTokenRules>(
                    &snippet_json_fixed,
                )?;
            }
            label => anyhow::bail!("Unexpected JSON code block tag: {label}"),
        };
        Ok(())
    });

    Ok(())
}

/// Removes any configurable options from the stringified action if existing,
/// ensuring that only the actual action name is returned. If the action consists
/// only of a string and nothing else, the string is returned as-is.
///
/// Example:
///
/// This will return the action name unmodified.
///
/// ```
/// let action_as_str = "workspace::Save";
/// let action_name = name_for_action(action_as_str);

View on GitHub (pinned to f4178619ac)

Solutions

1. Fix the tag in the markdown to one of the handled labels (e.g. `settings`, `semantic_token_rules`).
2. If the tag is intentionally new, add a match arm for it in the preprocessor before the `label =>` catch-all.
3. Re-run the preprocessor to confirm the docs build passes.

Example fix

```json setting     // before — typo, hits catch-all arm
{ "show_edit_predictions": true }
```

```json settings    // after — handled label
{ "show_edit_predictions": true }
```

// lint docs markdown for unknown block tags before running the preprocessor
const KNOWN = new Set(["settings", "semantic_token_rules" /* , other handled labels */]);
for (const m of markdown.matchAll(/```json\s+(\w+)/g)) {
  if (!KNOWN.has(m[1])) throw new Error(`Unexpected JSON code block tag: ${m[1]}`);
}

When it happens

Trigger: A markdown file under the docs tree containing a fenced code block whose info string resolves to an unhandled label — a typo like `"setting"`, a renamed tag, or a genuinely new tag category added without a match arm.

Common situations: Contributing new docs sections with a new block kind; renaming an existing tag in markdown but not the preprocessor; CI docs generation failing right after a markdown edit.

Related errors

• extension dir {} is not an absolute path
• failed to compile {} parser with clang: {}
• grammar directory '{}' already exists, but is not a git clon
• failed to run `git init` in directory '{}'
• No eval-cli binary provided. Either pass binary_path=/path/t

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