angular/angular-cli · error · Error

Unknown `$SHELL` environment variable value (${shell}). Angu

Error message

Unknown `$SHELL` environment variable value (${shell}). Angular CLI autocompletion only supports Bash or Zsh.

What it means

`initializeAutocomplete` passes the `$SHELL` value to `getShellRunCommandCandidates`, which only recognizes shells whose run commands/RC files it knows (Bash and Zsh). If `$SHELL` points to any other shell (fish, csh, nushell, etc.) no candidates are returned and the CLI throws this error since it cannot safely generate completion config for unknown shells.

Source

Thrown at packages/angular/cli/src/utilities/completion.ts:225

    throw new Error(
      '`$SHELL` environment variable not set. Angular CLI autocompletion only supports Bash or' +
        " Zsh. If you're on Windows, Cmd and Powershell don't support command autocompletion," +
        ' but Git Bash or Windows Subsystem for Linux should work, so please try again in one of' +
        ' those environments.',
    );
  }
  const home = env['HOME'];
  if (!home) {
    throw new Error(
      '`$HOME` environment variable not set. Setting up autocompletion modifies configuration files' +
        ' in the home directory and must be set.',
    );
  }

  // Get all the files we can add `ng completion` to which apply to the user's `$SHELL`.
  const runCommandCandidates = getShellRunCommandCandidates(shell, home);
  if (!runCommandCandidates) {
    throw new Error(
      `Unknown \`$SHELL\` environment variable value (${shell}). Angular CLI autocompletion only supports Bash or Zsh.`,
    );
  }

  // Get the first file that already exists or fallback to a new file of the first candidate.
  const candidates = await Promise.allSettled(
    runCommandCandidates.map((rcFile) => fs.access(rcFile).then(() => rcFile)),
  );
  const rcFile =
    candidates.find(
      (result): result is PromiseFulfilledResult<string> => result.status === 'fulfilled',
    )?.value ?? runCommandCandidates[0];

  // Append Angular autocompletion setup to RC file.
  try {
    await fs.appendFile(
      rcFile,
      '\n\n# Load Angular CLI autocompletion.\nsource <(ng completion script)\n',

View on GitHub (pinned to bb72145f9a)

Solutions

Switch to Bash or Zsh and re-run (e.g. `chsh -s /bin/bash`, then open a new terminal).
Temporarily override: `SHELL=/bin/bash ng completion` to write completion setup into your Bash RC.
Set up completion manually for your shell if it supports ng's completion script, or use shell-specific community completions.
Keep `$SHELL` set to bash/zsh for the duration of the command even if your interactive shell is different.

Example fix

// before
fish -c 'ng completion'   # SHELL=/usr/bin/fish -> throws
// after
SHELL=/bin/bash ng completion

Defensive patterns

Strategy: validation

Validate before calling

const shell = process.env.SHELL ?? '';
const supported = ['/bash', '/zsh'].some(s => shell.endsWith(s));
if (shell && !supported) {
  console.warn(`ng completion does not support $SHELL=${shell}; use bash or zsh.`);
}

Type guard

function isSupportedShell(shell: string | undefined): shell is string {
  return typeof shell === 'string' && /\/(ba)?sh$|\/zsh$/.test(shell);
}

Try / catch

try {
  await ngCompletionSetup();
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Unknown `$SHELL` environment variable value')) {
    // re-run under bash/zsh or configure completion manually
  } else { throw e; }
}

Prevention

Check `echo $SHELL` before running completion setup.
Use `SHELL=/bin/bash ng completion` to target bash RC files from another shell.
Switch login shell with chsh to bash/zsh if you want first-class support.
Consult the CLI docs for the supported-shell list before automating setup.

When it happens

Trigger: Running `ng completion` (via `run`/`considerSettingUpAutocompletion`) with `$SHELL` set to a non-Bash/Zsh shell path, e.g. `/usr/bin/fish`, `/bin/tcsh`, or `/usr/bin/nu`.

Common situations: Developers using fish or nushell as their login shell; macOS/Linux users with exotic shells; containers defaulting to dash/sh whose `$SHELL` is not bash/zsh.

Related errors

AI-assisted analysis of angular/angular-cli@bb72145f9a (2026-08-30). Data as JSON: /api/errors/50ffb579a6546173. Report an issue: GitHub.