facebook/docusaurus · error · Error

Docusaurus config flag future.faster.rspackPersistentCache r

Error message

Docusaurus config flag future.faster.rspackPersistentCache requires the flag future.faster.rspackBundler to be turned on.

What it means

Thrown during config post-processing when a user enables the `future.faster.rspackPersistentCache` flag without also enabling `future.faster.rspackBundler`. The persistent cache is a feature of the Rspack bundler, so it cannot function under the default Webpack bundler — Docusaurus rejects this combination rather than silently ignoring the cache flag. It is a hard dependency declared after the VCS config block in postProcessDocusaurusConfig.

Source

Thrown at packages/docusaurus/src/server/configValidation.ts:631

    config.onBrokenMarkdownLinks = undefined;
  }

  // We normalize the VCS config when using a boolean value
  if (typeof config.future.experimental_vcs === 'boolean') {
    const vcsConfig = config.future.experimental_vcs
      ? config.future.faster.gitEagerVcs
        ? getVcsPreset('default-v2')
        : getVcsPreset('default-v1')
      : getVcsPreset('disabled');

    config.future.experimental_vcs = vcsConfig;
  }

  if (
    config.future.faster.rspackPersistentCache &&
    !config.future.faster.rspackBundler
  ) {
    throw new Error(
      `Docusaurus config flag ${logger.code(
        'future.faster.rspackPersistentCache',
      )} requires the flag ${logger.code(
        'future.faster.rspackBundler',
      )} to be turned on.`,
    );
  }
}

// TODO move to @docusaurus/utils-validation
export function validateConfig(
  config: unknown,
  siteConfigPath: string,
): DocusaurusConfig {
  const {error, warning, value} = ConfigSchema.validate(config, {
    abortEarly: false,
  });

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Add `rspackBundler: true` alongside `rspackPersistentCache: true` in the `future.faster` block of docusaurus.config.js.
2. If you did not intend to switch bundlers, remove the `rspackPersistentCache` flag entirely.
3. Use the full `future: { faster: true }` shorthand to enable all faster flags consistently.

Example fix

// before
future: {
  faster: {
    rspackPersistentCache: true,
  },
},
// after
future: {
  faster: {
    rspackBundler: true,
    rspackPersistentCache: true,
  },
},

// Before applying future flags, check the dependency:
const faster = config.future?.faster ?? {};
if (faster.rspackPersistentCache && !faster.rspackBundler) {
  throw new Error('Enable future.faster.rspackBundler before rspackPersistentCache.');
}

function isValidFasterFlags(f: unknown): f is {rspackBundler?: boolean; rspackPersistentCache?: boolean} {
  if (!f || typeof f !== 'object') return true; // absence is valid
  const o = f as Record<string, unknown>;
  return !(o.rspackPersistentCache && !o.rspackBundler);
}

When it happens

Trigger: Setting `future: { faster: { rspackPersistentCache: true } }` in docusaurus.config.js while leaving `rspackBundler` unset/false. The check at configValidation.ts:631 fires whenever `config.future.faster.rspackPersistentCache` is truthy AND `config.future.faster.rspackBundler` is falsy.

Common situations: Copy-pasting only part of the `future.faster` preset from release notes; enabling the cache flag in isolation assuming it works on Webpack; upgrading Docusaurus and opting into speed flags piecemeal.

Related errors

• You can't use siteConfig.webpack.jsLoader and siteConfig.fut
• Unexpected "reportingSeverity" value: ${reportingSeverity}.
• ${JSON.stringify(redirect)} => Validation error: ${error.mes
• Can't reference blog post authors by a key (such as '${key}'
• You are using a feature of the Docusaurus docs plugin, but t

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