docs: add error message strings to relevant feature pages

Co-Authored-By: Devin Logan <devinannlogan@gmail.com>

Author: devin-ai-integration[bot]

fern/products/docs/pages/authentication/rbac.mdx

@@ -76,3 +76,17 @@ Use the `<If />` component to [conditionally render content](/learn/docs/writing
 ```
 
 You can also combine `roles` with `products` and `versions` props.
+
+## Common errors
+
+<Accordion title='Role "X" is used but not declared at the top level of the docs.yml file.'>
+  A `viewers:` entry or `<If roles={[...]}>` reference uses a role that isn't listed under the top-level `roles:` key in `docs.yml`. Add the role to the `roles` list:
+
+  ```yaml title="docs.yml"
+  roles:
+    - everyone
+    - partners
+    - beta-users
+    - admins
+  ```
+</Accordion>

fern/products/docs/pages/navigation/frontmatter.mdx

@@ -39,6 +39,10 @@ Frontmatter uses YAML syntax, but values are also processed as MDX. Some charact
 | `{` `}` `<` `>` | Escape with `\` | `title: "Using \<Callout\>"` |
 | `"` `'` | Opposite style or `\` | `title: 'The "best" practices'` |
 
+<Info title='Error: "Failed to parse frontmatter"'>
+  If `fern check` reports `Failed to parse frontmatter`, the YAML between the `---` markers is invalid. The most common cause is an unquoted value containing one of the special characters above. Wrap the value in quotes or escape the character and re-run `fern check`.
+</Info>
+
 ## Title
 
 <ParamField path="title" type="string" required={false} default="Page name from docs.yml">

fern/products/docs/pages/navigation/tabs.mdx

@@ -127,6 +127,20 @@ theme:
   Conditional display configuration
 </ParamField>
 
+### Common tab errors
+
+<AccordionGroup>
+  <Accordion title='Tab "X" is missing from the tabs configuration.'>
+    The `navigation` list references a tab key that isn't declared under the top-level `tabs` object. Add the tab to `tabs:` in `docs.yml` (with at least a `display-name`), or update the `- tab:` reference in `navigation` to match an existing key.
+  </Accordion>
+  <Accordion title='Tab "X" has both a href and layout. Only one should be used.'>
+    A tab entry combines `href` with `layout` or `variants`. Use `href` for external links, or `layout`/`variants` for internal content — not both.
+  </Accordion>
+  <Accordion title='Tab "X" is missing a href, layout, or variants.'>
+    Every tab in `navigation` must point somewhere. Add a `layout`, `variants`, or `href` to the tab entry.
+  </Accordion>
+</AccordionGroup>
+
 ## Tab variants
 
 Tab variants let you display different content variations within a single tab, and [support RBAC](/learn/docs/authentication/features/rbac). This is useful for showing different user types, implementation approaches, or experience levels without creating separate tabs.

fern/products/docs/pages/preview-publish/preview-changes-locally.mdx

@@ -48,6 +48,28 @@ Some features are disabled in local development:
 - Authentication
 </Note>
 
+### Common errors
+
+<AccordionGroup>
+  <Accordion title="No docs.yml file found. Please make sure your project has one.">
+    `fern docs dev` and `fern generate --docs` must be run from a directory that contains a `fern/` folder with a `docs.yml` inside. Change into your project directory, or create a `docs.yml` — see [Project structure](/learn/docs/getting-started/project-structure).
+  </Accordion>
+  <Accordion title="Broken link to /some/path (resolved path: ...)">
+    `fern check` reports this when a link in a Markdown page doesn't resolve to a real page, anchor, or file in your docs.
+
+    - For internal pages, use the [published URL path](/learn/docs/writing-content/markdown-basics#link-format) from your `docs.yml` config (for example, `/learn/docs/configuration/navigation`) — not a relative path or on-disk file path.
+    - For images and other assets, use a path relative to the Markdown file.
+
+    Broken internal links fail by default. Use [`fern generate --docs --no-strict-broken-links`](/learn/cli-api-reference/cli-reference/commands#fern-generate) to downgrade the failure to a warning while you fix them.
+  </Accordion>
+  <Accordion title="Invalid URL: /some/path">
+    A Markdown link or `<img src>` uses a value that isn't a valid URL. Check for typos, unescaped characters, or missing protocols on external links.
+  </Accordion>
+  <Accordion title="Path ./pages/foo.mdx does not exist">
+    A `path:` in `docs.yml` points to a file that isn't on disk. Fix the path or create the missing file. Paths are relative to the YAML file that defines them.
+  </Accordion>
+</AccordionGroup>
+
 ## Preview links
 
 Generate shareable preview URLs to review and collaborate on documentation changes before publishing. Preview links aren't indexed by search engines and don't expire.

fern/products/docs/pages/preview-publish/publishing-your-docs.mdx

@@ -192,3 +192,14 @@ If you need access to your docs offline or would like to host your docs on your
 
 To unpublish a docs site, navigate to the **Settings** page for your site in the [Fern Dashboard](https://dashboard.buildwithfern.com) and click **Unpublish**. This makes the domain no longer publicly accessible, but doesn't delete the site — you can republish it at any time. This is useful for creating draft sites or temporarily hiding a site from public view.
 
+## Common errors
+
+<AccordionGroup>
+  <Accordion title="No token found. Please set the FERN_TOKEN environment variable or run `fern login`.">
+    `fern generate --docs` needs an authenticated session to publish. Run `fern login` locally, or set `FERN_TOKEN` in your shell or CI environment. Use [`fern token`](/learn/cli-api-reference/cli-reference/commands#fern-token) to generate a CI-friendly token.
+  </Accordion>
+  <Accordion title="OpenAPI spec validation failed with N errors. Fix the errors above before generating docs.">
+    One or more OpenAPI specs referenced by the docs have fatal validation errors. The individual `<file>: <message>` lines above this message identify the exact problem — fix those in your spec, then re-run `fern generate --docs`.
+  </Accordion>
+</AccordionGroup>
+

fern/products/docs/pages/preview-publish/setting-up-your-domain.mdx

@@ -197,6 +197,22 @@ Once Fern has completed your setup, you'll be able to access your documentation
 </Accordion>
 </AccordionGroup> 
 
+### Common errors
+
+Errors below are surfaced by `fern check` and `fern generate --docs` when validating the `instances[].url` values in `docs.yml`.
+
+<AccordionGroup>
+  <Accordion title='Invalid URL format: "X". Expected format: <subdomain>.docs.buildwithfern.com'>
+    The `url` is missing a subdomain or uses an unexpected shape. Use `<your-org>.docs.buildwithfern.com` (for example, `plantstore.docs.buildwithfern.com`). Don't include `https://`.
+  </Accordion>
+  <Accordion title='Invalid domain in URL "X". The URL must end with one of: docs.buildwithfern.com, docs.dev.buildwithfern.com'>
+    The `url` doesn't end with a supported Fern domain. Update the `url` to end with `docs.buildwithfern.com`. Configure your vanity domain separately with `custom-domain`.
+  </Accordion>
+  <Accordion title='Invalid URL "X". A subdomain is required before docs.buildwithfern.com'>
+    The `url` is set to the bare domain. Add a subdomain prefix such as `<your-org>.docs.buildwithfern.com`.
+  </Accordion>
+</AccordionGroup>
+
 ### Multiple custom domains
 
 To serve your documentation from multiple custom domains (e.g., for partner or white-label deployments), follow the above steps for each domain (subdomain, subpath, or root domain), then configure an array in your `docs.yml`:
@@ -211,4 +227,4 @@ instances:
 
 <Info>
 After configuring multiple domains in your `docs.yml`, contact Fern via your dedicated Slack channel or [email](mailto:support@buildwithfern.com) to complete the setup. You'll receive DNS configuration details for each domain.
-</Info>                        
+</Info>                                                

fern/products/docs/pages/seo/redirects.mdx

@@ -12,3 +12,34 @@ subtitle: Learn how to configure redirects in Fern Docs. Set up exact path redir
   To add external links to your sidebar navigation, see [Navigation](/learn/docs/configuration/navigation#links).
 </Tip>
 
+## Common errors
+
+Errors below are surfaced by `fern check` and `fern generate --docs`.
+
+<AccordionGroup>
+  <Accordion title='Page "X" was moved from "/old" to "/new". The old URL will return 404 without a redirect.'>
+    A page's slug changed relative to the last published version of your docs. Add a redirect in `docs.yml` so existing links keep working:
+
+    ```yaml title="docs.yml"
+    redirects:
+      - source: /old
+        destination: /new
+    ```
+  </Accordion>
+  <Accordion title='Page "X" was removed. The previously published URL "/old" will return 404 without a redirect.'>
+    A published page no longer exists in the navigation. Add a redirect to another relevant page to avoid breaking incoming links:
+
+    ```yaml title="docs.yml"
+    redirects:
+      - source: /old
+        destination: /new-home
+    ```
+  </Accordion>
+  <Accordion title='Redirect from "/path" to "/path" creates an infinite loop (source equals destination).'>
+    A redirect's `source` and `destination` are the same path. Remove the redirect or point the `destination` at a different URL.
+  </Accordion>
+  <Accordion title="Circular redirect chain detected: /a → /b → /a">
+    Two or more redirects form a cycle. Update the chain so each `source` eventually resolves to a single final `destination`.
+  </Accordion>
+</AccordionGroup>
+