facebook/docusaurus · error · Error

Extension "${ext}" contains a "." (dot) which is not allowed

Error message

Extension "${ext}" contains a "." (dot) 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 are plain tokens (e.g. 'html'); the plugin adds the leading dot itself via addLeadingDot, so a user-supplied dot would create a double dot ('..html') and is rejected.

Source

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

import {
  addTrailingSlash,
  removeSuffix,
  removeTrailingSlash,
} 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}`;

/**

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Drop the leading dot: use 'html' instead of '.html'.
2. If generating extensions from path.extname(file), slice off the first character: ext.slice(1).
3. Keep extensions as single tokens with no dot, slash, or URI-unsafe characters.

Example fix

// before
fromExtensions: ['.html'],
// after
fromExtensions: ['html'],

function stripLeadingDot(ext: string): string {
  if (ext.startsWith('.')) {
    throw new Error(`Extension "${ext}" contains a "." which is not allowed. Use "${ext.slice(1)}".`);
  }
  return ext;
}

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

When it happens

Trigger: Configuring fromExtensions: ['.html'] or toExtensions: ['html.json']; passing extensions that include a filename-style value. Reached in the same forEach(validateExtension) loop as the other extension checks.

Common situations: Intuitively writing '.html' because that is how extensions look in filenames; copying a config snippet from a blog that uses dotted extensions; feeding file extensions extracted with path.extname (which includes the dot).

Related errors

• Extension "${ext}" is not allowed. If the redirect extension
• Extension "${ext}" contains a "/" (slash) which is not allow
• 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/f6fbdf9f3f621bc9. Report an issue: GitHub.