{"record":{"id":"c639f9ef009ae038","repo":"facebook/docusaurus","slug":"formattederror","errorCode":null,"errorMessage":"${formattedError}","messagePattern":"\\$\\{formattedError\\}","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/docusaurus/src/server/configValidation.ts","lineNumber":671,"sourceCode":"    const unknownFields = error.details.reduce((formattedError, err) => {\n      if (err.type === 'object.unknown') {\n        return `${formattedError}\"${err.path.reduce((acc, cur) =>\n          typeof cur === 'string' ? `${acc}.${cur}` : `${acc}[${cur}]`,\n        )}\",`;\n      }\n      return formattedError;\n    }, '');\n    let formattedError = error.details.reduce(\n      (accumulatedErr, err) =>\n        err.type !== 'object.unknown'\n          ? `${accumulatedErr}${err.message}\\n`\n          : accumulatedErr,\n      '',\n    );\n    formattedError = unknownFields\n      ? `${formattedError}These field(s) (${unknownFields}) are not recognized in ${siteConfigPath}.\\nIf you still want these fields to be in your configuration, put them in the \"customFields\" field.\\nSee https://docusaurus.io/docs/api/docusaurus-config/#customfields`\n      : formattedError;\n    throw new Error(formattedError);\n  }\n\n  postProcessDocusaurusConfig(value);\n\n  return value;\n}\n","sourceCodeStart":653,"sourceCodeEnd":678,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus/src/server/configValidation.ts#L653-L678","documentation":"Thrown by `validateConfig` when Joi's `ConfigSchema.validate` rejects the user's docusaurus.config. Non-unknown-field errors are concatenated, and if any `object.unknown` details exist, an extra message lists them and points users at the `customFields` escape hatch. It is the single chokepoint for all site config schema failures.","triggerScenarios":"Any `ConfigSchema.validate(config, {abortEarly:false})` failure: typos in top-level keys (e.g. `tilte` instead of `title`), wrong types (e.g. `url: 123`), or arbitrary unrecognized root keys. The code at configValidation.ts:652-671 collects all Joi details and re-throws a single composed Error.","commonSituations":"Misspelled config keys; passing plugin options at the root instead of via presets/plugins; upgrading Docusaurus and using a removed/renamed config field; copy-pasting a v2 config into a v3 site.","solutions":["Read the printed field list — each unrecognized field is quoted with its path (`.foo.bar`) — and remove or rename it.","Move genuinely custom, non-Docusaurus data into the `customFields` object instead of the config root.","Run `pnpm docusaurus start` again after each fix to surface remaining errors (abortEarly:false reports all at once).","Cross-check the field against https://docusaurus.io/docs/api/docusaurus-config for your version."],"exampleFix":"// before (wrong: typo + unknown key)\nexport default {\n  tilte: 'My Site',\n  myCustomThing: 42,\n};\n// after\nexport default {\n  title: 'My Site',\n  customFields: { myCustomThing: 42 },\n};","handlingStrategy":"validation","validationCode":"import {ConfigSchema} from '@docusaurus/types'; // or import the schema if exposed\n// Pre-validate in a CI script:\nconst {error} = ConfigSchema.validate(userConfig, {abortEarly: false, allowUnknown: false});\nif (error) console.error(error.details.map(d => d.message).join('\\n'));","typeGuard":"function isKnownConfigKey(key: string): boolean {\n  // maintain a set of valid root keys for your Docusaurus version\n  const known = new Set(['title','url','baseUrl','i18n','presets','plugins','themes','customFields'/*,...*/]);\n  return known.has(key);\n}","tryCatchPattern":"try {\n  const cfg = await loadConfig(siteConfigPath);\n  start(cfg);\n} catch (e) {\n  if (e instanceof Error && /not recognized|customFields/.test(e.message)) {\n    console.error('Config schema error — fix unknown fields:', e.message);\n  }\n  throw e;\n}","preventionTips":["Keep custom data under `customFields` only — never at the config root.","Add a TypeScript type annotation (`satisfies Config` / `: Config`) to your docusaurus.config.ts.","Run a `docusaurus start` smoke test in CI after every config change."],"tags":["config","validation","joi","schema"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}