{"record":{"id":"20fb7c15552f918e","repo":"facebook/docusaurus","slug":"swizzle-config-does-not-match-expected-schema-r","errorCode":null,"errorMessage":"Swizzle config does not match expected schema: ${result.error.message}","messagePattern":"Swizzle config does not match expected schema: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/docusaurus/src/commands/swizzle/config.ts","lineNumber":68,"sourceCode":"const SwizzleConfigSchema = Joi.object<SwizzleConfig>({\n  components: Joi.object()\n    .pattern(\n      Joi.string(),\n      Joi.object({\n        actions: Joi.object().pattern(\n          Joi.string().valid(...SwizzleActions),\n          Joi.string().valid(...SwizzleActionsStatuses),\n        ),\n        description: Joi.string(),\n      }),\n    )\n    .required(),\n});\n\nfunction validateSwizzleConfig(unsafeSwizzleConfig: unknown): SwizzleConfig {\n  const result = SwizzleConfigSchema.validate(unsafeSwizzleConfig);\n  if (result.error) {\n    throw new Error(\n      `Swizzle config does not match expected schema: ${result.error.message}`,\n    );\n  }\n  return result.value;\n}\n\nexport function normalizeSwizzleConfig(\n  unsafeSwizzleConfig: unknown,\n): SwizzleConfig {\n  const swizzleConfig = validateSwizzleConfig(unsafeSwizzleConfig);\n\n  // Ensure all components always declare all actions\n  Object.values(swizzleConfig.components).forEach((componentConfig) => {\n    SwizzleActions.forEach((action) => {\n      if (!componentConfig.actions[action]) {\n        componentConfig.actions[action] = 'unsafe';\n      }\n    });","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus/src/commands/swizzle/config.ts#L50-L86","documentation":"Thrown by `validateSwizzleConfig` when a theme's `swizzle.config.js` fails the Joi schema (each component entry must declare `actions` as a required array of `[action, status]` tuples from the allowed SwizzleActions/SwizzleActionsStatuses enums, with an optional `description`). This is almost always a theme-author bug, not an end-user config mistake.","triggerScenarios":"A theme package ships a malformed `swizzle.config.js` — missing `actions`, wrong tuple shape, unknown action/status string, or wrong top-level shape — and the user runs any swizzle command against that theme.","commonSituations":"Custom/in-house theme with a hand-written `swizzle.config.js`; third-party theme with an incompatible schema version; typo in an action name (e.g. `'ejct'` instead of `'eject'`); forgetting the `actions` array entirely.","solutions":["Open the offending theme's `swizzle.config.js` and fix the reported Joi error (the message names the failing field).","Ensure every component entry has `actions: [['wrap'|'eject', 'safe'|'unsafe'|'forbidden'], ...]` and an optional `description`.","If the theme is third-party, update it (`pnpm update <theme>`) or file an issue with the maintainer.","As a temporary workaround, swizzle a different theme or remove the broken entry from the theme config."],"exampleFix":"// before (theme's swizzle.config.js)\nexport default {\n  components: {\n    SearchBar: { actions: ['wrap'] }, // wrong shape\n  },\n};\n// after\nexport default {\n  components: {\n    SearchBar: { actions: [['wrap', 'safe']], description: 'Search input' },\n  },\n};","handlingStrategy":"validation","validationCode":"import Joi from 'joi';\nconst {error} = SwizzleConfigSchema.validate(unsafeSwizzleConfig);\nif (error) throw new Error(`Fix theme swizzle.config.js: ${error.message}`);","typeGuard":null,"tryCatchPattern":"try { await normalizeSwizzleConfig(cfg); }\ncatch (e) {\n  if (/Swizzle config does not match/.test(e.message)) {\n    console.error('Theme author must fix swizzle.config.js — see schema'); process.exit(1);\n  }\n  throw e;\n}","preventionTips":["Theme authors: unit-test `swizzle.config.js` against the schema on every change.","Pin the Docusaurus version that matches your theme's schema.","Validate theme configs in CI before publishing the theme."],"tags":["swizzle","theme","config","validation","joi"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}