---
title: Troubleshooting
description: 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

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](/docs/reference/diagnostics) lists every code.

## 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](/docs/reference/cli/check).

## reed check errors

- [Fix "uses unknown component" (DS-S06)](/docs/troubleshooting/unknown-component) — a
  typo, a component from another platform, or an alias that needs a dialect.
- [Fix component contract errors (DS-S01 to DS-S05, DS-S07)](/docs/troubleshooting/component-contract)
  — a disallowed child, a `Steps` with one `Step`, a missing prop, a bad enum value, or
  nesting that is forbidden or too deep.
- [Fix "has an image with no non-empty alt text" (DS-A01)](/docs/troubleshooting/image-missing-alt)
  — including `alt=""` and images inside a `Frame`.
- [Fix "has an H1 in its body" or "skips a heading level" (DS-A02)](/docs/troubleshooting/heading-order)
  — including a page that starts at `###`.
- [Fix "is not referenced by any navigation entry" (content-page-not-in-navigation)](/docs/troubleshooting/build-fails-page-not-in-navigation)
  — a file in the content directory that `navigation` does not list.

## Build failures

- [Fix "Expected a closing tag" for a code block inside a component](/docs/troubleshooting/fenced-code-in-component)
  — `unparseable-mdx` from a fenced block inside `Card`, `Step`, `Tab` or `Accordion`.
- [Fix reed build failing with a missing or stale prefetch](/docs/troubleshooting/prefetch-missing-or-stale)

## It built but the site is wrong

- [Fix links that work in reed dev but 404 in production](/docs/troubleshooting/links-404-in-production)
- [Fix images that do not show on the built site](/docs/troubleshooting/images-not-showing)
- [Fix llms.txt or .md pages downloading instead of displaying](/docs/troubleshooting/markdown-served-as-download)
- [Fix a whole site that 404s after a successful deploy](/docs/troubleshooting/base-mount-404)

## 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](/docs/authoring/mdx-pitfalls)
once. It covers the four mistakes behind most of these pages.