typst/typst · error

invalid document structure, this element's PDF tag would be

Error message

invalid document structure, this element's PDF tag would be split up

What it means

Raised in progress_tree_end when a tag element cannot be kept contiguous in the PDF tag tree and the affected span is non-breakable under PDF/UA rules (a BreakOpportunity::NoPdfUa was encountered). Unlike the validator-prefixed variant, this fires because PDF/UA conformance forbids splitting the element at all.

Source

Thrown at crates/typst-pdf/src/tags/tree/build.rs:663

        (None, Some(_)) => Ok(split_inner_groups(tree, outer.parent, stack_idx)),
        (None, None) => {
            let non_breakable_span = inner_non_breakable_span.or(outer.span);

            let non_breakable_in_pdf_ua = inner_non_breakable_in_pdf_ua
                || matches!(outer_break_opportunity, BreakOpportunity::NoPdfUa(_));

            if non_breakable_in_pdf_ua {
                let validator =
                    tree.options.standards.config.validators().to_comma_list();
                bail!(
                    non_breakable_span,
                    "{validator} error: invalid document structure, \
                     this element's PDF tag would be split up";
                    hint: "this is probably caused by paragraph grouping";
                    hint: "maybe you've used a `parbreak`, `colbreak`, or `pagebreak`";
                );
            } else {
                bail!(
                    non_breakable_span,
                    "invalid document structure, \
                     this element's PDF tag would be split up";
                    hint: "please report this as a bug";
                );
            }
        }
    }
}

/// Consider the following introspection tags:
/// ```txt
/// start a
///   start b
///     start c
/// end   a
///     end   c
///   end   b

View on GitHub (pinned to 6a6f1a97a3)

Solutions

1. Keep the element on one page or within one region so its tag stays contiguous
2. Remove explicit keep-together or non-breakable constraints that conflict with the layout
3. Avoid nesting constructs whose tag structure cannot be preserved when broken

When it happens

Trigger: Thrown at crates/typst-pdf/src/tags/tree/build.rs:663 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of typst/typst@6a6f1a97a3 (2026-08-17). Data as JSON: /api/errors/525426f4f31a3285. Report an issue: GitHub.