astral-sh/ruff · error · syn::Error

Mandatory `example` field is missing in `#[option]` attribut

Error message

Mandatory `example` field is missing in `#[option]` attribute. Add an example using `#[option(example="..")]`.

What it means

Compile-time error from the #[option] macro's field-attribute parser. Each #[option] field must supply an example value, which ruff embeds in generated configuration documentation; if parse_field_attributes (reached through handle_option) collects default and value_type but never an example, it raises this error at the attribute's span. It is a developer-facing authoring error in ruff's own rule/option definitions, resolved by adding example=".." to the #[option(...)] attribute; it aborts macro expansion rather than being recoverable at runtime.

Source

Thrown at crates/ruff_macros/src/config.rs:288

        Ok(())
    })?;

    let Some(default) = default else {
        return Err(syn::Error::new(
            attribute.span(),
            "Mandatory `default` field is missing in `#[option]` attribute. Specify the default using `#[option(default=\"..\")]`.",
        ));
    };

    let Some(value_type) = value_type else {
        return Err(syn::Error::new(
            attribute.span(),
            "Mandatory `value_type` field is missing in `#[option]` attribute. Specify the value type using `#[option(value_type=\"..\")]`.",
        ));
    };

    let Some(example) = example else {
        return Err(syn::Error::new(
            attribute.span(),
            "Mandatory `example` field is missing in `#[option]` attribute. Add an example using `#[option(example=\"..\")]`.",
        ));
    };

    Ok(FieldAttributes {
        default,
        value_type,
        example,
        scope,
    })
}

fn parse_deprecated_attribute(attribute: &Attribute) -> syn::Result<DeprecatedAttribute> {
    let mut deprecated = DeprecatedAttribute::default();
    attribute.parse_nested_meta(|meta| {
        if meta.path.is_ident("note") {
            deprecated.note = Some(get_string_literal(&meta, "note", "deprecated")?.value());

View on GitHub (pinned to 26f38c119c)

Solutions

1. Add #[option(example = "...")] with a valid config snippet
2. Run cargo dev generate-all after adding the example

When it happens

Trigger: Thrown at crates/ruff_macros/src/config.rs:288 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of astral-sh/ruff@26f38c119c (2026-09-05). Data as JSON: /api/errors/377f37da6c25439a. Report an issue: GitHub.