Swizzle config does not match expected schema: ${result.erro

Error message

Swizzle config does not match expected schema: ${result.error.message}

What it means

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.

Source

Thrown at packages/docusaurus/src/commands/swizzle/config.ts:68

const SwizzleConfigSchema = Joi.object<SwizzleConfig>({
  components: Joi.object()
    .pattern(
      Joi.string(),
      Joi.object({
        actions: Joi.object().pattern(
          Joi.string().valid(...SwizzleActions),
          Joi.string().valid(...SwizzleActionsStatuses),
        ),
        description: Joi.string(),
      }),
    )
    .required(),
});

function validateSwizzleConfig(unsafeSwizzleConfig: unknown): SwizzleConfig {
  const result = SwizzleConfigSchema.validate(unsafeSwizzleConfig);
  if (result.error) {
    throw new Error(
      `Swizzle config does not match expected schema: ${result.error.message}`,
    );
  }
  return result.value;
}

export function normalizeSwizzleConfig(
  unsafeSwizzleConfig: unknown,
): SwizzleConfig {
  const swizzleConfig = validateSwizzleConfig(unsafeSwizzleConfig);

  // Ensure all components always declare all actions
  Object.values(swizzleConfig.components).forEach((componentConfig) => {
    SwizzleActions.forEach((action) => {
      if (!componentConfig.actions[action]) {
        componentConfig.actions[action] = 'unsafe';
      }
    });

View on GitHub (pinned to 3f483e80e3)

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.

Example fix

// before (theme's swizzle.config.js)
export default {
  components: {
    SearchBar: { actions: ['wrap'] }, // wrong shape
  },
};
// after
export default {
  components: {
    SearchBar: { actions: [['wrap', 'safe']], description: 'Search input' },
  },
};

Defensive patterns

Strategy: validation

Validate before calling

import Joi from 'joi';
const {error} = SwizzleConfigSchema.validate(unsafeSwizzleConfig);
if (error) throw new Error(`Fix theme swizzle.config.js: ${error.message}`);

Try / catch

try { await normalizeSwizzleConfig(cfg); }
catch (e) {
  if (/Swizzle config does not match/.test(e.message)) {
    console.error('Theme author must fix swizzle.config.js — see schema'); process.exit(1);
  }
  throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/20fb7c15552f918e. Report an issue: GitHub.