Skip to content
Reed Docs

Troubleshooting

How to read reed check output, what a DS-* code means, and a fix page for each common failure.

Each page here starts from one symptom — an exact message or a visible behaviour — and walks through cause, fix and how to prove it is fixed. Search for the message you are seeing, or find it in the lists below.

What a DS-* code is

Section titled “What a DS-* code is”

Reed checks every page against its component catalog and a small set of accessibility rules before it builds anything. Each problem it finds is a diagnostic: a code, a severity and a message.

The code tells you which family the problem belongs to:

  • DS-S* — structure. Unknown components, bad children, missing props, bad nesting. Always errors.
  • DS-A* — accessibility. Missing alt text, heading order, unlabeled icon links. Always errors.
  • DS-D* — design and density. Suggestions and silently dropped props. Warnings, unless you escalate them.

A few diagnostics have plain names instead of DS-* codes, such as unparseable-mdx for a page MDX cannot parse, unsupported-upstream-component for a component your configured dialect has no equivalent for, and content-page-not-in-navigation for a page that navigation does not list. Those three are errors, but not every plain-named diagnostic is: some are warnings. Each output line prints its own severity, so read the marker rather than the name.

The diagnostics reference lists every code.

Reading reed check output

Section titled “Reading reed check output”

reed check validates docs.json and every page without building, and needs no network. Its output is one line per diagnostic, indented two spaces, then a verdict:

txt
  ✗ [DS-S02] content file "guides/setup.mdx"'s "Steps" has 1 element child(ren); minimum required is 2
  ✗ [DS-A02] content file "guides/setup.mdx" skips a heading level (h1 → h3)
  ⚠ [DS-D06] content file "guides/setup.mdx" has 3 adjacent callout-family elements; consider grouping
check failed.

Read each line left to right:

  • ✗ or ⚠. ✗ is an error and blocks the build. ⚠ is a warning and does not — unless you pass --strict-components (escalates DS-D*) or --strict-tokens (escalates every other warning). An escalated warning prints as ✗.
  • The code in brackets. Use it to find the fix page below.
  • The file. Paths are relative to your content directory.
  • The rest. It names the component and, for contract errors, the contract it was judged against. That contract name is the first thing to read when a diagnostic looks wrong: it tells you which rules Reed applied after dialect mapping.

Messages name the file but not the line. Search the file for the component or heading the message quotes.

A passing run ends with check passed. reed build runs exactly the same checks first, so fix what check reports before you start a build. It is faster and gives the same answer. See reed check.

reed check errors

Section titled “reed check errors”

Build failures

Section titled “Build failures”

It built but the site is wrong

Section titled “It built but the site is wrong”

Before you dig in

Section titled “Before you dig in”

Most failures on this list are cheaper to catch than to debug. Run reed check on every pull request — it is offline and fast — and read MDX pitfalls once. It covers the four mistakes behind most of these pages.