remix-run/remix · error · UsageError

Unknown completion shell: ${shell}

Error message

Unknown completion shell: ${shell}

What it means

The completion command accepts a single shell argument and currently only recognizes one supported shell; any other value (or none, since undefined fails the guard) is rejected as an unknown completion shell.

Source

Thrown at packages/cli/src/lib/commands/completion.ts:39

    return 0
  }

  if (argv[0] === '--') {
    return runCompletionPlumbing(argv.slice(1))
  }

  if (argv.includes('-h') || argv.includes('--help')) {
    process.stdout.write(getCompletionCommandHelpText())
    return 0
  }

  let [shell, ...rest] = argv

  try {
    parseArgs(rest, {}, { maxPositionals: 0 })

    if (!isCompletionShell(shell)) {
      throw unknownCompletionShell(shell)
    }

    process.stdout.write(getCompletionScript())
    return 0
  } catch (error) {
    process.stderr.write(
      renderCliError(toCliError(error), {
        helpText: getCompletionCommandHelpText(process.stderr),
      }),
    )
    return 1
  }
}

export function getCompletionCommandHelpText(target: NodeJS.WriteStream = process.stdout): string {
  return formatHelpText(
    {
      description: 'Print a shell completion script for Remix.',

View on GitHub (pinned to 9696913134)

Solutions

1. Pass the supported shell name shown by remix completion --help (e.g. remix completion bash)
2. Update the CLI to a version that supports your shell if one exists
3. If your shell is unsupported, wire manual completion from the emitted script or skip it

Example fix

# before
$ remix completion zsh

# after
$ remix completion bash

const SUPPORTED_SHELLS = new Set(['bash']) // match isCompletionShell

function shellIsSupported(shell?: string): boolean {
  return shell != null && SUPPORTED_SHELLS.has(shell)
}

function isCompletionShell(shell: string | undefined): shell is 'bash' {
  return shell === 'bash'
}

try {
  runCompletionCommand(argv)
} catch (error) {
  if (/Unknown completion shell/.test(error.message)) printSupportedShells()
  else throw error
}

When it happens

Trigger: runCompletionCommand finds shell is not a value accepted by isCompletionShell — e.g. remix completion zsh or remix completion fish when only bash is supported, or remix completion with no argument.

Common situations: Users on zsh/fish following generic clap-style docs; automated shell setup snippets that pass $SHELL basename; missing argument in scripted dotfiles.

Related errors

• Invalid completion request.
• throw new AssertionError(options)
• ${matcherName} requires a mock function with a .mock.calls p
• throw new AssertionError({ message, actual, expected, operat
• expect(received).toThrow() requires a function (got ${typeof

AI-assisted analysis of remix-run/remix@9696913134 (2026-08-27). Data as JSON: /api/errors/06336845da6ba05a. Report an issue: GitHub.