typst/typst · error

please specify the figure's supplement

Error message

please specify the figure's supplement

What it means

Raised during FigureElem synthesis: the supplement is auto, the figure's kind has no localizable name, and no caption/supplement is available, so Typst cannot form a caption like 'Figure 1'.

Source

Thrown at crates/typst-library/src/model/figure.rs:377

                .unwrap_or_else(|| FigureKind::Elem(ImageElem::ELEM))
        });

        // Resolve the supplement.
        let supplement = match elem.supplement.get_ref(styles).as_ref() {
            Smart::Auto => {
                // Default to the local name for the kind, if available.
                let name = match &kind {
                    FigureKind::Elem(func) => func
                        .local_name(
                            styles.get(TextElem::lang),
                            styles.get(TextElem::region),
                        )
                        .map(TextElem::packed),
                    FigureKind::Name(_) => None,
                };

                if numbering.is_some() && name.is_none() {
                    bail!(span, "please specify the figure's supplement")
                }

                Some(name.unwrap_or_default())
            }
            Smart::Custom(None) => None,
            Smart::Custom(Some(supplement)) => {
                // Resolve the supplement with the first descendant of the kind or
                // just the body, if none was found.
                let descendant = match kind {
                    FigureKind::Elem(func) => elem
                        .body
                        .query_first_naive(&Selector::Elem(func, None))
                        .map(Cow::Owned),
                    FigureKind::Name(_) => None,
                };

                let target = descendant.unwrap_or_else(|| Cow::Borrowed(&elem.body));
                Some(supplement.resolve(engine, styles, [target])?)

View on GitHub (pinned to 35417aa769)

Solutions

1. Set `supplement` explicitly, e.g. `supplement: [Diagram]`
2. Add a caption to the figure
3. Use a kind whose name Typst knows (e.g. image, table)

When it happens

Trigger: Thrown at crates/typst-library/src/model/figure.rs:377 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of typst/typst@35417aa769 (2026-08-17). Data as JSON: /api/errors/2ee7c5224bed8419. Report an issue: GitHub.