{"record":{"id":"922f8819e3dc5289","repo":"angular/angular-cli","slug":"home-environment-variable-not-set-setting-up-a","errorCode":null,"errorMessage":"`$HOME` environment variable not set. Setting up autocompletion modifies configuration files in the home directory and must be set.","messagePattern":"`\\$HOME` environment variable not set\\. Setting up autocompletion modifies configuration files in the home directory and must be set\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/angular/cli/src/utilities/completion.ts","lineNumber":216,"sourceCode":" * Sets up autocompletion for the user's terminal. This attempts to find the configuration file for\n * the current shell (`.bashrc`, `.zshrc`, etc.) and append a command which enables autocompletion\n * for the Angular CLI. Supports only Bash and Zsh. Returns whether or not it was successful.\n * @return The full path of the configuration file modified.\n */\nexport async function initializeAutocomplete(): Promise<string> {\n  // Get the currently active `$SHELL` and `$HOME` environment variables.\n  const shell = env['SHELL'];\n  if (!shell) {\n    throw new Error(\n      '`$SHELL` environment variable not set. Angular CLI autocompletion only supports Bash or' +\n        \" Zsh. If you're on Windows, Cmd and Powershell don't support command autocompletion,\" +\n        ' but Git Bash or Windows Subsystem for Linux should work, so please try again in one of' +\n        ' those environments.',\n    );\n  }\n  const home = env['HOME'];\n  if (!home) {\n    throw new Error(\n      '`$HOME` environment variable not set. Setting up autocompletion modifies configuration files' +\n        ' in the home directory and must be set.',\n    );\n  }\n\n  // Get all the files we can add `ng completion` to which apply to the user's `$SHELL`.\n  const runCommandCandidates = getShellRunCommandCandidates(shell, home);\n  if (!runCommandCandidates) {\n    throw new Error(\n      `Unknown \\`$SHELL\\` environment variable value (${shell}). Angular CLI autocompletion only supports Bash or Zsh.`,\n    );\n  }\n\n  // Get the first file that already exists or fallback to a new file of the first candidate.\n  const candidates = await Promise.allSettled(\n    runCommandCandidates.map((rcFile) => fs.access(rcFile).then(() => rcFile)),\n  );\n  const rcFile =","sourceCodeStart":198,"sourceCodeEnd":234,"githubUrl":"https://github.com/angular/angular-cli/blob/bb72145f9ab45aee29f523236b3a25cd0813a841/packages/angular/cli/src/utilities/completion.ts#L198-L234","documentation":"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.","triggerScenarios":"Invoking `ng completion` (via `run` or `considerSettingUpAutocompletion`) with `$SHELL` set but `HOME` missing from the environment.","commonSituations":"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.","solutions":["Set the home directory before running: `export HOME=/home/myuser` (or `/root`).","Ensure the CLI runs as a user that has a home directory (`useradd -m`).","In containers/CI, pass `-e HOME=/root` to `docker run` or set HOME in the pipeline environment.","Skip completion setup if not needed (`NG_CLI_COMPLETION=false`)."],"exampleFix":"// before (CI job)\n- run: npx ng completion\n// after\n- run: export HOME=/root && npx ng completion","handlingStrategy":"validation","validationCode":"if (!process.env.HOME) {\n  console.warn('Skipping ng completion: $HOME is not set.');\n} else {\n  // safe to invoke ng completion\n}","typeGuard":"function hasHomeEnv(env: NodeJS.ProcessEnv): env is NodeJS.ProcessEnv & { HOME: string } {\n  return typeof env.HOME === 'string' && env.HOME.length > 0;\n}","tryCatchPattern":"try {\n  await ngCompletionSetup();\n} catch (e) {\n  if (e instanceof Error && e.message.includes('$HOME` environment variable not set')) {\n    // run with an explicit HOME or skip setup\n  } else { throw e; }\n}","preventionTips":["Ensure service users in CI/containers have HOME set (e.g. -e HOME=/root).","Prefer users created with a home directory (useradd -m).","Verify env completeness (HOME, SHELL) in Docker/systemd/cron before CLI setup steps.","Skip autocompletion setup in ephemeral environments."],"tags":["environment","home-directory","autocompletion","angular-cli"],"backgroundTag":"missing-env-var","analyzedSha":"bb72145f9ab45aee29f523236b3a25cd0813a841","analyzedAt":"2026-08-30T02:47:34.745Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}