angular/angular-cli · error · Error

`$HOME` environment variable not set. Setting up autocomplet

Error message

`$HOME` environment variable not set. Setting up autocompletion modifies configuration files in the home directory and must be set.

What it means

After validating `$SHELL`, `initializeAutocomplete` reads `$HOME` because autocompletion setup appends a `source <(ng completion script)` line to shell RC files in the user's home directory. Without `$HOME` the CLI cannot locate or create those configuration files, so it throws this error.

Source

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

 * Sets up autocompletion for the user's terminal. This attempts to find the configuration file for
 * the current shell (`.bashrc`, `.zshrc`, etc.) and append a command which enables autocompletion
 * for the Angular CLI. Supports only Bash and Zsh. Returns whether or not it was successful.
 * @return The full path of the configuration file modified.
 */
export async function initializeAutocomplete(): Promise<string> {
  // Get the currently active `$SHELL` and `$HOME` environment variables.
  const shell = env['SHELL'];
  if (!shell) {
    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 =

View on GitHub (pinned to bb72145f9a)

Solutions

1. Set the home directory before running: `export HOME=/home/myuser` (or `/root`).
2. Ensure the CLI runs as a user that has a home directory (`useradd -m`).
3. In containers/CI, pass `-e HOME=/root` to `docker run` or set HOME in the pipeline environment.
4. Skip completion setup if not needed (`NG_CLI_COMPLETION=false`).

Example fix

// before (CI job)
- run: npx ng completion
// after
- run: export HOME=/root && npx ng completion

if (!process.env.HOME) {
  console.warn('Skipping ng completion: $HOME is not set.');
} else {
  // safe to invoke ng completion
}

function hasHomeEnv(env: NodeJS.ProcessEnv): env is NodeJS.ProcessEnv & { HOME: string } {
  return typeof env.HOME === 'string' && env.HOME.length > 0;
}

try {
  await ngCompletionSetup();
} catch (e) {
  if (e instanceof Error && e.message.includes('$HOME` environment variable not set')) {
    // run with an explicit HOME or skip setup
  } else { throw e; }
}

When it happens

Trigger: Invoking `ng completion` (via `run` or `considerSettingUpAutocompletion`) with `$SHELL` set but `HOME` missing from the environment.

Common situations: CI containers running as a service user without a home directory, systemd/cron jobs with a minimal environment, Docker images where `HOME` is unset for the runtime user, IDE-spawned terminals with scrubbed env.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• `$SHELL` environment variable not set. Angular CLI autocompl
• Unknown `$SHELL` environment variable value (${shell}). Angu
• Failed to append autocompletion setup to `${rcFile}`.
• Warning: The current version of Node (${nodeVersion}) is not
• Could not find ${level} workspace.

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