PDF Accessibility

PDF Accessibility API: How to Handle an Appropriate Nesting Failed Error

An “appropriate nesting failed” result usually points to an invalid PDF tag-tree relationship. Follow a diagnostic and repair workflow, then review reading order, tables, images, forms, and other accessibility issues.

People in the office

If your PDF accessibility API returns “appropriate nesting failed”, treat it as a tag-tree problem first, not as an API outage. The checker is usually telling you that a structural element in the PDF is sitting under the wrong parent, at the wrong level, or inside an element that does not make sense for assistive technology.

The fix is not to restyle the page. Open the detailed finding, locate the failing tag, inspect its parent and children, repair or rebuild that branch, then recheck reading order and review the section with a screen reader or equivalent assistive-technology test.

Updated November 20, 2026.

What “appropriate nesting failed” means in a PDF

A tag is structural information attached to PDF content. It tells assistive technology whether something is a heading, paragraph, list, table, link, figure, form field, or artifact, meaning decorative or irrelevant content that should be ignored.

The tag tree is the document’s machine-readable structure. It is separate from what the page looks like. A page can look perfect visually while the tag tree says something else: a heading might be nested inside a paragraph, a list item might sit outside its list, or a table cell might be attached to the wrong table branch.

“Appropriate nesting failed” usually means one part of that hierarchy is invalid or not meaningful. Structural elements need valid parent-child relationships. A paragraph belongs in a sensible document section, list items belong inside lists, table rows and cells belong inside the correct table structure, and links or figures should not be buried under arbitrary wrappers that hide their purpose.

The phrase is also checker-specific. It is not a universal PDF error message, and it is not necessarily an API failure. Some tools expose this as a PDF/UA-related structural finding. Adobe Acrobat guidance and many institutional guides discuss “Appropriate nesting” in the context of heading structure; for example, Eastern Washington University’s Acrobat guidance says the rule checks that headings are in proper order and tells users to expand the failed item and inspect the element involved (Eastern Washington University).

That does not mean every “appropriate nesting” result in every checker is caused by the same tag. Compare the result with the checker’s own documentation, especially if the output comes from an API or batch workflow that maps PDF/UA, WCAG, or Matterhorn-style checks into custom result names. PDF/UA is the ISO standard for accessible PDF structure; WCAG is the Web Content Accessibility Guidelines, often referenced when evaluating digital content including PDFs.

The key point: visual appearance is a weak signal. A heading can be bold, large, and centered on the page while its tag is nested in the wrong branch. A table can look like a table while the tags describe unrelated paragraphs. A checker is looking at structure, not typography.

How to locate the tag-tree branch that failed

Start with the detailed result, not the dashboard total. A summary score cannot tell you what to repair.

Record four things from the checker output:

  • Page or object location: where the affected content appears.

  • Tag type: such as H2, P, L, LI, Table, TR, TH, TD, Link, Figure, or Artifact.

  • Parent information: what contains the failing tag.

  • Child information: what the failing tag contains.

If the checker reports only “appropriate nesting failed” with no useful context, open the same PDF in a tag editor and inspect likely problem areas in order: headings, lists, tables, links, figures, and artifacts.

In Adobe Acrobat Pro, the relevant panels and commands are product-specific, not universal PDF concepts. Adobe’s accessibility documentation describes Acrobat’s tools for creating, checking, and fixing accessible PDFs, including its accessibility checker and tag-related repair workflow (Adobe Help). WebAIM also notes that Acrobat’s accessibility tools, including tags and order panels, need to be available in the workspace before meaningful review and repair can happen (WebAIM).

Once the tag panel is open, do not look only at the failed element. Look at the branch around it:

  • Parent: Is this element inside the right container?

  • Siblings: Are nearby elements at the same structural level?

  • Children: Does this element contain only the kinds of content it should contain?

  • Reading sequence: Does the branch match the order in which the content should be read?

A common mistake is to inspect the failed tag in isolation. The tag may be fine; the parent may be wrong. A heading tag might be correctly labeled as a heading but placed under another heading, paragraph, table cell, or layout wrapper in a way that breaks the hierarchy.

Check these likely sources one at a time.

Incorrect heading hierarchy. A heading is not just large text. It marks a section level. If an H3 appears before any H2 in that section, or if a visual subheading has been tagged at the wrong level, a checker may flag nesting or hierarchy. Acrobat-specific “Appropriate nesting” guidance commonly focuses on this heading-order problem (Eastern Washington University).

Paragraphs inside invalid wrappers. Export tools sometimes wrap ordinary text in unnecessary containers. A paragraph may end up inside a span-like structure, figure, table cell, or heading branch where it does not belong.

List items outside a list. A proper list needs list structure, not just bullet characters. If bullet text is tagged as separate paragraphs, or list item labels and bodies are split into the wrong branches, screen readers may not announce the list correctly.

Table cells under the wrong table branch. Tables are especially prone to structural damage after export or auto-tagging. Rows, header cells, and data cells need to sit under the right table structure. Clemson’s PDF remediation guidance on complex tags covers repairs to lists, tables, and link object references in Acrobat, which are exactly the kinds of structures to inspect when a branch looks wrong (Clemson University).

Links attached to unsuitable parents. A link needs both visible or meaningful link text and the correct tagged relationship to its annotation. A link object reference attached to the wrong tag can leave the reading experience broken even if the link works with a mouse.

Figures treated as ordinary text. A meaningful image should be tagged as a figure and have a useful picture description, often called alt text. Alt text is the short description assistive technology can announce for an image. Decorative images should usually be artifacts, not figures.

Decorative content not marked as an artifact. Page borders, divider lines, repeated background shapes, and purely decorative icons can clutter the tag tree. If they are treated as real content, they can create awkward nesting and reading-order problems.

How to repair an appropriate-nesting failure

Repair the smallest branch that explains the finding. Do not retag the whole document unless the surrounding structure is too damaged to trust.

The practical sequence is:

  1. Select the failed tag in the detailed result. If the checker can jump to the tag or show it in the structure panel, use that rather than searching visually.

  2. Inspect its parent and children. The visible text may be correct while the structural relationship is wrong.

  3. Decide what the content is. Is it a section heading, paragraph, list item, table header, data cell, link, figure, form label, or decorative artifact?

  4. Move or retag the element. Put it under the right parent and remove redundant wrappers that do not express meaningful structure.

  5. Retest that finding. Re-run the same check on the repaired section or document.

  6. Review reading order. A structural repair can change, expose, or fail to fix the order in which assistive technology reaches the content.

Reading order is the sequence in which assistive technology encounters content. It is not always the same as the visual order, especially in multi-column layouts, sidebars, footnotes, forms, and tables.

For simple heading failures, repair may mean changing a heading level or moving the heading to the correct section branch. For list failures, it may mean rebuilding the list structure so list items sit under the list and labels/bodies are not scattered as unrelated paragraphs. For tables, it may mean rebuilding the table branch rather than trying to drag individual cells around until the checker stops reporting the same item.

If the branch is severely damaged, rebuild it from the page content. Repeated small patches can leave a structure that is technically different but still incoherent. A clean rebuild is often faster for complex tables, multi-column exports, or PDFs produced by design tools that created a shallow or arbitrary tag tree.

A broader PDF remediation workflow is useful when the same error appears across many pages or when the document has related structural findings. The nesting error is often one symptom of a larger tagging problem, not the whole problem.

After the edit, do not stop at “the error disappeared.” Recheck the repaired section in context. The tag tree should match what the page means, not merely satisfy one rule.

Why fixing this one error is not enough

Resolving an appropriate-nesting finding does not prove that the PDF is accessible, compliant, certified, or conformant with PDF/UA or WCAG. It provides evidence about one structural test.

A repaired tag tree can still fail users in ordinary ways:

  • Reading order may still be wrong. The structure can be cleaner while a screen reader still jumps from a heading to a footer, sidebar, or second column.

  • Picture descriptions may be missing or inaccurate. A checker can detect the presence of a figure description more easily than it can judge whether the description says the right thing.

  • List semantics may be broken. Bullets may look correct but not be announced as a list.

  • Table headers and scope may be incomplete. A table can have rows and cells but still fail to communicate which headers apply to which data.

  • Form fields may lack usable names, labels, instructions, or keyboard order.

  • Document language and title metadata may be missing. These affect how assistive technology identifies and announces the document.

  • Artifacts may be wrong. Decorative content may be read aloud, or meaningful content may be hidden as decoration.

The non-obvious failure mode is that a structurally repaired PDF can become “more correct” to a checker while still being confusing to a person. A table may use valid tags but need human judgment to decide whether a cell is a header. A chart may have a figure tag and alt text but still need a meaningful description. A multi-column page may have valid tags but the wrong sequence.

Automated checkers are useful because they find structural conditions at scale. They are not judges of meaning. Ordecto’s deeper article on what automated PDF accessibility checkers cannot test is worth reading when a team is treating checker output as release evidence.

If this is one PDF in a larger collection, track the repair as part of a document review process. For large sets, a PDF accessibility audit should separate machine-detectable issues from issues that require human review, so the team does not mistake a quieter report for a usable archive.

Use a PDF accessibility tool when manual repair is slowing you down

Manual repair works when the affected branch is small and clear. It slows down when the PDF has many repeated failures, damaged tables, inconsistent headings, or content exported from tools that created poor tags.

Ordecto, a PDF accessibility tool from the team behind Otio, checks PDFs against PDF/UA-1 with WCAG 2.2 as a referenced test model. Its findings are listed as failed, needs a person, or not tested; a machine result is not shown as “accessible.”

The relevant workflow is straightforward:

  1. Upload the PDF.

  2. Inspect structural findings, including tag-related issues.

  3. Repair common document structures such as headings, paragraphs, lists, tables, links, figures, form fields, and reading order.

  4. Review items that need human judgment.

  5. Download the repaired PDF and an accessibility report.

That report matters because it records what was checked, what changed, and what still needs a person. It is review evidence, not a certificate.

For teams focused on PDF/UA-related structural findings, a PDF/UA checker can help separate document-structure problems from broader review tasks. If the same classes of issues keep appearing, Ordecto’s page on common PDF accessibility errors gives examples of the kinds of faults that often cluster together.

Use a tool to speed up detection and repair. Keep a person in the loop for meaning: reading order, complex tables, form behavior, and picture descriptions.

Retest the repaired section with a person

Run the original checker again after repair. Confirm whether the appropriate-nesting result has changed, and compare the before-and-after report.

Then test the repaired section like a reader would encounter it. Use a keyboard and a screen reader, or an equivalent assistive-technology review process, and listen for the structure rather than just watching the page.

Focus on the repaired branch first:

  • Does the heading sequence make sense?

  • Are paragraph boundaries clear?

  • Are lists announced as lists?

  • Do tables announce useful row and column relationships?

  • Do links make sense out of context?

  • Are figures described accurately?

  • Are decorative items skipped?

  • Do form fields have usable labels and instructions?

If the document contains complex tables, formulas, multilingual content, fillable forms, footnotes, sidebars, or unusual page layouts, assign focused human review. Common tagging rules will not answer every judgment call.

Keep the final report with the reviewed PDF. That gives the team a record of the original finding, the repair, and the remaining items that required human assessment. Ordecto’s article on testing PDF accessibility with screen readers after remediation explains why this final review catches problems that structural checks alone miss.

The practical next action: check the PDF with the free checker, repair the flagged tag-tree branch, and review the repaired section before publishing or delivering the file.

FAQ

Q: Is “appropriate nesting failed” an API error?
A: Not necessarily. It usually describes a structural problem in the PDF tag tree, but the exact wording is checker-specific and should be interpreted using that checker’s detailed result and documentation.

Q: Can I fix an appropriate-nesting error without retagging the whole PDF?
A: Often, yes. Repair the affected tag branch by correcting parent-child relationships or removing accidental wrappers; rebuild a larger section only when the existing structure is too damaged to interpret reliably.

Q: Does passing the nesting check mean the PDF is accessible?
A: No. It provides evidence about one structural test only. Reading order, picture meaning, complex tables, forms, and other issues still need broader checks and human review.

Q: What should I check after repairing the nesting error?
A: Retest the tag structure and review the repaired section with assistive technology. Also check reading order, headings, lists, tables, links, picture descriptions, artifacts, forms, language, metadata, and any other findings in the report.