facebook/docusaurus · error · Error

Extension "${ext}" contains a "/" (slash) which is not allow

Error message

Extension "${ext}" contains a "/" (slash) which is not allowed.
If the redirect extension system is not good enough for your use case, you can create redirects yourself with the "createRedirects" plugin option.

What it means

Thrown by validateExtension() when an extension string in fromExtensions/toExtensions contains a '/' character. Extensions must be flat tokens; a slash would turn the extension into a path segment and produce redirect paths that cross directories, which the plugin forbids.

Source

Thrown at packages/docusaurus-plugin-client-redirects/src/extensionRedirects.ts:30

} from '@docusaurus/utils-common';
import type {RedirectItem} from './types';

const ExtensionAdditionalMessage =
  'If the redirect extension system is not good enough for your use case, you can create redirects yourself with the "createRedirects" plugin option.';

const validateExtension = (ext: string) => {
  if (!ext) {
    throw new Error(
      `Extension "${ext}" is not allowed.\n${ExtensionAdditionalMessage}`,
    );
  }
  if (ext.includes('.')) {
    throw new Error(
      `Extension "${ext}" contains a "." (dot) which is not allowed.\n${ExtensionAdditionalMessage}`,
    );
  }
  if (ext.includes('/')) {
    throw new Error(
      `Extension "${ext}" contains a "/" (slash) which is not allowed.\n${ExtensionAdditionalMessage}`,
    );
  }
  if (encodeURIComponent(ext) !== ext) {
    throw new Error(
      `Extension "${ext}" contains invalid URI characters.\n${ExtensionAdditionalMessage}`,
    );
  }
};

const addLeadingDot = (extension: string) => `.${extension}`;

/**
 * Create new `/path` that redirects to existing an `/path.html`
 */
export function createToExtensionsRedirects(
  paths: string[],
  extensions: string[],

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Use a bare extension with no slash: 'html' instead of 'html/v2'.
2. If you need path-level redirects, use the createRedirects option instead of fromExtensions/toExtensions.
3. Sanitize generated arrays: ext.replaceAll('/', '').

Example fix

// before
toExtensions: ['html/v2'],
// after
toExtensions: ['html'],

function assertNoSlash(ext: string): void {
  if (ext.includes('/')) {
    throw new Error(`Extension "${ext}" contains a "/" which is not allowed.`);
  }
}

const isFlatExtension = (e: unknown): e is string =>
  typeof e === 'string' && !!e && !e.includes('/') && !e.includes('.')
  && encodeURIComponent(e) === e;

When it happens

Trigger: Configuring fromExtensions: ['html/v2'] or toExtensions: ['a/b']; passing a path fragment instead of a bare extension. Reached in the same forEach(validateExtension) loop.

Common situations: Mistakenly passing a relative path or a versioned folder fragment as an extension; building the array by splitting a pathname on '.' and keeping a segment that contains '/'.

Related errors

• Extension "${ext}" is not allowed. If the redirect extension
• Extension "${ext}" contains a "." (dot) which is not allowed
• Extension "${ext}" contains invalid URI characters. If the r
• Some created redirects are invalid: - ${redirectValidationEr
• You are trying to create client-side redirections to invalid

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