facebook/docusaurus · error · Error

You are trying to create client-side redirections to invalid

Error message

You are trying to create client-side redirections to invalid paths.

What it means

Thrown by validateCollectedRedirects() in @docusaurus/plugin-client-redirects when one or more redirects point to a `to` path that does not exist as a route (or exists only with a different trailing-slash form than what trailingSlash config permits). The error message distinguishes trailing-slash issues from truly nonexistent paths and lists both the bad paths and the valid alternatives.

Source

Thrown at packages/docusaurus-plugin-client-redirects/src/collectRedirects.ts:162

      message += `
These paths do exist, but because you have explicitly set trailingSlash=${trailingSlashConfig}, you need to write the path ${
        trailingSlashConfig ? 'with trailing slash' : 'without trailing slash'
      }:
- ${trailingSlashIssues.map(([p]) => p).join('\n- ')}
`;
    }

    if (invalidPaths.length) {
      message += `
These paths are redirected to but do not exist:
- ${invalidPaths.map(([p]) => p).join('\n- ')}

Valid paths you can redirect to:
- ${allowedToPaths.join('\n- ')}
`;
    }

    throw new Error(message);
  }
}

function filterUnwantedRedirects(
  redirects: RedirectItem[],
  pluginContext: PluginContext,
): RedirectItem[] {
  // We don't want to create the same redirect twice, since that would lead to
  // writing the same html redirection file twice.
  Object.entries(_.groupBy(redirects, (redirect) => redirect.from)).forEach(
    ([from, groupedFromRedirects]) => {
      if (groupedFromRedirects.length > 1) {
        logger.report(
          pluginContext.siteConfig.onDuplicateRoutes,
        )`name=${'@docusaurus/plugin-client-redirects'}: multiple redirects are created with the same "from" pathname: path=${from}
It is not possible to redirect the same pathname to multiple destinations:${groupedFromRedirects.map(
          (r) => JSON.stringify(r),
        )}`;

View on GitHub (pinned to 3f483e80e3)

Solutions

If the error says 'because you have explicitly set trailingSlash=...', rewrite each listed path with (or without) the trailing slash to match your config.
If the error says 'do not exist', point each listed redirect.to at one of the 'Valid paths' also printed in the message.
Re-run the build; the validator re-checks the full list.

Example fix

// before (trailingSlash: true)
redirects: [{ from: '/old', to: '/guide' }]
// after
redirects: [{ from: '/old', to: '/guide/' }]

Defensive patterns

Strategy: validation

Validate before calling

import {addTrailingSlash, removeTrailingSlash} from '@docusaurus/utils-common';
function alignWithTrailingSlash(p: string, trailingSlash: boolean | undefined): string {
  if (trailingSlash === true) return addTrailingSlash(p);
  if (trailingSlash === false) return removeTrailingSlash(p);
  return p;
}
// apply to each redirect.to before passing to the plugin

Prevention

When you change trailingSlash, audit every redirect.to.
Point redirects at canonical route paths printed by the validator.
Keep redirects and route generation in the same config so they stay in sync.

When it happens

Trigger: A redirect whose to:'/guide' when the site only has '/guide/' (or vice versa) while trailingSlash is explicitly set; a redirect to a path that was never created; renaming a doc and forgetting to update its redirects.

Common situations: Changing the trailingSlash config and forgetting to update redirect targets; renaming/moving a doc without updating createRedirects; pointing redirects at a path that is itself generated by a plugin that was disabled.

Related errors

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