---
title: Known import gaps
description: Every diagnostic the importer emits, what it means, and what you must fix by hand.
---

The importer reports what it could not carry across. This page is that list.

## The severity rule

One rule decides every diagnostic's severity, and it is worth knowing because it tells you
what you can safely ignore:

> **Content or config you explicitly declared would never appear in the output → error.**
> **Presentation degrades to a default while the content itself is retained → warning.**

An error means something would go missing. A warning means something looks different.
Neither is silently dropped, and the first class cannot exit zero.

## `fern-conversion-error` — errors

Conversion stops. Fix these before anything else.

| Case | Meaning |
|---|---|
| A `docs.yml` field references a path outside the Fern project | Absolute paths, `..` traversal and project-escaping symlinks are refused. No file outside the source project is read or copied. |
| Navigation that cannot be represented | The declared structure has no equivalent in Reed's tab/group/page model. |

## `fern-unsupported-field` — warnings

Converted, with something dropped.

| Case | What happens |
|---|---|
| A referenced file does not exist in the Fern project | The field is dropped. |
| `styles.css` resolves outside the project via a symlink | Not copied; no `customCss` entry is emitted. Your custom styling is simply absent. |
| An unrecognized top-level `docs.yml` key | Ignored. |
| An unrecognized `colors` key or mode | That colour degrades to the template default. |
| A `tabs.<id>` key other than `display-name` | Ignored. |

The `styles.css` case deserves attention: it is classified a warning because your *content*
survives, but a site whose entire custom stylesheet vanished will not look like the one you
migrated from. Check for this specifically.

## `fern-path-disambiguated` — warnings

Two things collided and the second was renamed.

| Case | What happens |
|---|---|
| Two Fern pages normalize to the same page path | The second is renamed. **Any link pointing at it is now wrong.** |
| Two assets share a basename | The second is copied under a different name. |

Page-path collisions are the most expensive warning in this list. The page still exists,
so nothing errors — but inbound links, cross-references and any external link to the
original path now resolve to the wrong page or to nothing. Grep your content for links to
every disambiguated path.

## Component-level gaps come later

Import produces MDX; whether that MDX renders is a separate question answered by
`reed check`. Expect `DS-*` diagnostics on top of the import diagnostics, especially
`DS-S03` before you set `content.dialect`, and `DS-D08` where a Fern prop has no
representation in Reed's component contract.

`DS-D08` is a warning that means a prop you wrote is being discarded. Read every one of
them — the page renders, but not with everything you asked for. See
[Diagnostics](/docs/reference/diagnostics).

## Accent colour derivation

Fern derives a family of colours from a single accent. Reed takes six explicit colour
keys instead, so a Fern accent does not carry its derived ramp across — you set the six
keys yourself. The result is a site that is close but not identical, and the difference is
in the derived shades rather than the primary colour.

## What none of this covers

The importer converts a Fern project's structure and config. It does not review your
information architecture, rewrite prose written for another platform's components, or tell
you which pages are now redundant. Those are editorial decisions, and a migration is a
good moment to make them rather than carry them forward.