mui/material-ui · error · Error

docs-infra: The description "${description}" is too long (${

Error message

docs-infra: The description "${description}" is too long (${description.length} characters).\nIt needs to have fewer than 170 characters—ideally less than 160. For more details, see:\nhttps://ahrefs.com/blog/meta-description/#4-be-concise\n

What it means

prepareMarkdown caps the docs page description at 160 characters (with a hard ceiling of 170 referenced in the message) to match search-engine meta-description truncation. A longer description fails the build rather than silently being cut off in search results.

Source

Thrown at packages-internal/markdown/prepareMarkdown.mjs:119

      }

      if (title.length > 70) {
        throw new Error(
          [
            `docs-infra: The title "${title}" is too long (${title.length} characters).`,
            'It needs to have fewer than 70 characters—ideally less than 60. For more details, see:',
            'https://developers.google.com/search/docs/advanced/appearance/title-link',
            '',
          ].join('\n'),
        );
      }

      if (description == null || description === '') {
        throw new Error(`docs-infra: Missing description in the page: ${location}\n`);
      }

      if (description.length > 160) {
        throw new Error(
          [
            `docs-infra: The description "${description}" is too long (${description.length} characters).`,
            'It needs to have fewer than 170 characters—ideally less than 160. For more details, see:',
            'https://ahrefs.com/blog/meta-description/#4-be-concise',
            '',
          ].join('\n'),
        );
      }

      if (description.slice(-1) !== '.' && description.slice(-1) !== '!') {
        throw new Error(
          `docs-infra: The description "${description}" should end with a "." or "!", those are sentences.`,
        );
      }

      const contents = getContents(markdown);

      if (headers.components.length > 0 && headers.productId !== 'base-ui') {

View on GitHub (pinned to bdc96df2cb)

Solutions

Trim the `description:` header to under 160 characters.
Move excess detail into the page body.
Re-run `pnpm docs:build` to confirm.

Example fix

---
description: A description that rambles on for well over one hundred and sixty characters and includes far more information than any search engine snippet would ever display usefully...
---
// after
---
description: A concise summary of the page, under 160 characters.
---

Defensive patterns

Strategy: validation

Validate before calling

function validateDescription(description) {
  if (description.length > 160) throw new Error(`Description too long: ${description.length}`);
  return description;
}

Prevention

Enforce description length <= 160 in a docs lint rule.
Run `pnpm docs:build` locally before pushing.
Keep descriptions as one concise sentence.

When it happens

Trigger: Writing a `description:` frontmatter header longer than 160 characters; the build runs the length check and throws.

Common situations: Verbose description copied from body prose; description that grows during translation.

Related errors

AI-assisted analysis of mui/material-ui@bdc96df2cb (2026-08-12). Data as JSON: /api/errors/e2e6d0590cae0a7a. Report an issue: GitHub.