clap-rs/clap · error

feature not enabled {event:?}

Error message

feature not enabled {event:?}

What it means

This is a runtime panic (`unimplemented!`) inside clap_derive's markdown doc-comment renderer, `parse_markdown` in `clap_derive/src/utils/doc_comments.rs:401`. The function is only compiled when the `unstable-markdown` Cargo feature is enabled (it pulls in `pulldown-cmark` + `anstyle`); it turns /// doc comments into styled help text. The match arm panics for pulldown-cmark events that clap does not yet know how to render: footnote definitions/references, definition lists, tables, metadata blocks, superscript/subscript, inline/display math, and task-list markers. The message literally means "this markdown feature is recognized by the parser but rendering support is not enabled/implemented in clap."

Source

Thrown at clap_derive/src/utils/doc_comments.rs:401

                )
                | Event::End(
                    TagEnd::FootnoteDefinition
                    | TagEnd::DefinitionList
                    | TagEnd::DefinitionListTitle
                    | TagEnd::DefinitionListDefinition
                    | TagEnd::Table
                    | TagEnd::TableHead
                    | TagEnd::TableRow
                    | TagEnd::TableCell
                    | TagEnd::MetadataBlock(_)
                    | TagEnd::Superscript
                    | TagEnd::Subscript,
                )
                | Event::InlineMath(_)
                | Event::DisplayMath(_)
                | Event::FootnoteReference(_)
                | Event::TaskListMarker(_) => {
                    unimplemented!("feature not enabled {event:?}")
                }
            }
        }
        let short = short.unwrap_or_else(|| writer.output.trim_end().to_owned());
        let long = writer.output.trim_end();
        let long = has_details.then(|| long.to_owned());
        (short, long)
    }
}

View on GitHub (pinned to ccc92c3b11)

Solutions

1. Remove the unsupported markdown construct (tables, footnotes, math, task lists, definition lists, super/subscript, metadata blocks) from the /// doc comment and replace it with syntax clap supports: headings, paragraphs, emphasis/strong/strike-through, inline code, links, ordered/unordered lists, and blockquotes.
2. If you need the feature genuinely, disable `unstable-markdown` (remove it from `features`) so doc comments are treated as plain text and `parse_markdown` is never called, until clap adds support.
3. Track/check the clap CHANGELOG for the `unstable-markdown` feature; because it is unstable, supported event coverage changes between versions, so pin the clap version whose renderer matches your doc-comment content.

Example fix

// before (clap with features = ["unstable-markdown"])
/// Render a table.
///
/// | col a | col b |
/// |-------|-------|
/// | 1     | 2     |
#[derive(clap::Parser)]
struct Cli { name: String }

// after
/// Render a table.
///
/// col a: 1, col b: 2
#[derive(clap::Parser)]
struct Cli { name: String }

// Pre-build / CI check. Only needed if you enable clap's `unstable-markdown` feature.
// clap_derive's markdown help renderer hits unimplemented!("feature not enabled {event:?}")
// during macro expansion for the constructs below when present in `///` doc comments on
// #[derive(Parser|Args|Subcommand|ValueEnum)] items.
use pulldown_cmark::{Event, Options, Parser, Tag};

fn unsupported_markdown_in_docs(doc: &str) -> Option<&'static str> {
    for ev in Parser::new_ext(doc, Options::all()) {
        match ev {
            Event::Start(Tag::FootnoteDefinition(_)) => return Some("footnote"),
            Event::Start(Tag::DefinitionList | Tag::DefinitionListTitle | Tag::DefinitionListDefinition) => return Some("definition list"),
            Event::Start(Tag::Table(_) | Tag::TableHead | Tag::TableRow | Tag::TableCell) => return Some("table"),
            Event::Start(Tag::MetadataBlock(_)) => return Some("metadata block"),
            Event::Start(Tag::Superscript | Tag::Subscript) => return Some("super/subscript"),
            Event::InlineMath(_) | Event::DisplayMath(_) => return Some("math"),
            Event::FootnoteReference(_) => return Some("footnote reference"),
            Event::TaskListMarker(_) => return Some("task list"),
            _ => {}
        }
    }
    None
}

// usage over each extracted doc-comment string before `cargo build`:
// if let Some(bad) = unsupported_markdown_in_docs(&doc) { /* strip or rewrite it */ }

When it happens

Trigger: Enable the `unstable-markdown` feature (e.g. `clap = { version = "4", features = ["unstable-markdown"] }`) and write a /// doc comment containing unsupported markdown: a footnote `[^1]`, a GFM table, an inline/display math `$x$`/`$$x$$`, a task list `- [x]`, a definition list, a metadata block, or super/subscript `^x^`/`~x~`. The panic fires when the doc comment is actually processed — i.e. when help text is rendered via `--help`, `-h`, or when an arg-parse error prints usage. It does NOT fire at compile time.

Common situations: Adopting the experimental `unstable-markdown` feature to get rich help formatting and pasting README-style markdown (which often contains tables, footnotes, or task lists) into struct doc comments. Upgrading pulldown-cmark across clap versions can newly emit events (e.g. `Tag::MetadataBlock`, definition lists) for syntax that used to be ignored. Copying markdown from GitHub/issues into `///` blocks is the typical trigger.

Related errors

• cannot `#[flatten]` an `Option<Args>` with `#[group(skip)]`

AI-assisted analysis of clap-rs/clap@ccc92c3b11 (2026-08-01). Data as JSON: /data/errors/2f78dc12159cc08c.json. Report an issue: GitHub.