Skip to content

docs: add error message strings to relevant feature pages#4980

Draft
devin-ai-integration[bot] wants to merge 3 commits intomainfrom
devin/1776387241-docs-error-strings
Draft

docs: add error message strings to relevant feature pages#4980
devin-ai-integration[bot] wants to merge 3 commits intomainfrom
devin/1776387241-docs-error-strings

Conversation

@devin-ai-integration
Copy link
Copy Markdown
Contributor

Summary

Adds "Common errors" sections to existing docs feature pages so users can paste an error string from fern check / fern generate --docs into docs search (or a search engine) and land on the right page. Per Devin's guidance in the Slack thread, errors live alongside the relevant feature rather than in a standalone troubleshooting page.

Errors were pulled from the fern CLI docs validator rules (packages/cli/yaml/docs-validator/src/rules/*) and the generate/generateDocsWorkspace command. Each accordion quotes the user-facing error string in its title and explains the fix.

Pages updated:

  • seo/redirects.mdx — missing-redirects (moved/removed), circular-redirects (self-loop, chain)
  • navigation/tabs.mdx — tab not declared, tab has both href + layout, tab missing any target
  • navigation/frontmatter.mdxFailed to parse frontmatter (inline <Info> next to the Special characters table)
  • authentication/rbac.mdx — role used but not declared
  • preview-publish/setting-up-your-domain.mdx — three Invalid URL ... variants for instances[].url
  • preview-publish/preview-changes-locally.mdxNo docs.yml file found, broken link, invalid URL, Path ... does not exist
  • preview-publish/publishing-your-docs.mdxNo token found ..., OpenAPI spec validation failure

Scope is intentionally "docs only, to start" — SDK and other error surfaces are not covered here.

Review & Testing Checklist for Human

  • Spot-check a couple of error strings against what Fern actually prints. I lifted the wording from source rule files (e.g. valid-markdown-link, missing-redirects-logic, valid-instance-url, all-roles-must-be-declared, tab-with-href, filepaths-exist, valid-frontmatter, generateDocsWorkspace), but I didn't run the CLI against a broken fixture to confirm the exact casing/punctuation users see.
  • For setting-up-your-domain.mdx, verify the listed valid domains (docs.buildwithfern.com, docs.dev.buildwithfern.com) match the full VALID_FERN_DOMAINS list in the validator. I used two examples; the real list may differ.
  • Confirm any new cross-links resolve on the preview, especially /learn/cli-api-reference/cli-reference/commands#fern-generate and /learn/docs/writing-content/markdown-basics#link-format. Other anchors used (#fern-token) already appeared elsewhere in the repo.
  • Sanity-check the accordion titles render correctly — a few contain quotes, parentheses, and an arrow character (). If any look off in preview, the title attribute may need different quoting.

Test plan: open the preview URL, visit each updated page, expand each new accordion, and confirm content renders and internal links work.

Notes

  • fern check on the branch surfaces the same 2 pre-existing SDK errors as main (CreateCodeRecordRequest / CreateDocumentRequest already declared) — unrelated to this PR.
  • Vale isn't installed in this environment, so style checks weren't run locally. CI should cover it.
  • No changelog entry added since this is content-only additions to existing pages, not a new feature.

Link to Devin session: https://app.devin.ai/sessions/7b48f89348e04d43bf5d6518e7f9939a
Requested by: @devalog

Co-Authored-By: Devin Logan <devinannlogan@gmail.com>
@devin-ai-integration
Copy link
Copy Markdown
Contributor Author

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment and CI monitoring

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`.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 [vale] reported by reviewdog 🐶
[FernStyles.Adverbs] Remove 'separately' if it's not important to the meaning of the statement.

devin-ai-integration bot and others added 2 commits April 17, 2026 00:59
Co-Authored-By: Devin Logan <devinannlogan@gmail.com>
Co-Authored-By: Devin Logan <devinannlogan@gmail.com>
@devalog devalog marked this pull request as draft April 17, 2026 01:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant