{"record":{"id":"7ce0654c3d7b67bb","repo":"angular/angular-cli","slug":"failed-to-append-autocompletion-setup-to-rcfile","errorCode":null,"errorMessage":"Failed to append autocompletion setup to `${rcFile}`.","messagePattern":"Failed to append autocompletion setup to `(.+?)`\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/angular/cli/src/utilities/completion.ts","lineNumber":247,"sourceCode":"\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 =\n    candidates.find(\n      (result): result is PromiseFulfilledResult<string> => result.status === 'fulfilled',\n    )?.value ?? runCommandCandidates[0];\n\n  // Append Angular autocompletion setup to RC file.\n  try {\n    await fs.appendFile(\n      rcFile,\n      '\\n\\n# Load Angular CLI autocompletion.\\nsource <(ng completion script)\\n',\n    );\n  } catch (err) {\n    assertIsError(err);\n    throw new Error(`Failed to append autocompletion setup to \\`${rcFile}\\`.`, { cause: err });\n  }\n\n  return rcFile;\n}\n\n/** Returns an ordered list of possible candidates of RC files used by the given shell. */\nfunction getShellRunCommandCandidates(shell: string, home: string): string[] | undefined {\n  if (shell.toLowerCase().includes('bash')) {\n    return ['.bashrc', '.bash_profile', '.profile'].map((file) => path.join(home, file));\n  } else if (shell.toLowerCase().includes('zsh')) {\n    return ['.zshrc', '.zsh_profile', '.profile'].map((file) => path.join(home, file));\n  } else {\n    return undefined;\n  }\n}\n\n/**\n * Returns whether the user has a global CLI install.","sourceCodeStart":229,"sourceCodeEnd":265,"githubUrl":"https://github.com/angular/angular-cli/blob/bb72145f9ab45aee29f523236b3a25cd0813a841/packages/angular/cli/src/utilities/completion.ts#L229-L265","documentation":"When appending the autocompletion bootstrap line (`source <(ng completion script)`) to the chosen shell RC file, an I/O failure from `fs.appendFile` is caught, wrapped via `assertIsError`, and rethrown with this message and the original error as `cause`. It means the CLI could not write to the RC file, not that autocompletion itself failed.","triggerScenarios":"`initializeAutocomplete` calling `fs.appendFile(rcFile, ...)` which rejects due to permissions, a read-only filesystem, the path being a directory, or disk-full conditions.","commonSituations":"Home directory or RC file owned by another user / read-only permissions; running inside a container with a read-only `$HOME`; network home directories (NFS) unavailable; `$HOME` pointing to a non-writable path.","solutions":["Fix permissions on the RC file: `chmod u+w ~/.bashrc` (or take ownership with `chown`).","Check `err.cause` (the underlying Node error) to see the precise filesystem failure (EACCES, EROFS, EISDIR, ENOSPC).","Append the line manually if the CLI cannot: add `source <(ng completion script)` to your `~/.bashrc`/`~/.zshrc`.","Free disk space or remount the filesystem read-write if ENOSPC/EROFS is reported."],"exampleFix":"// inspect the wrapped cause\ntry { await ngCompletion(); } catch (e) {\n  console.error(e.cause); // e.g. EACCES: permission denied, open '/home/user/.bashrc'\n}\n// shell fix\nchmod u+w ~/.bashrc","handlingStrategy":"try-catch","validationCode":"import { access, constants } from 'node:fs/promises';\nawait access(rcFile, constants.W_OK); // throws early if the RC file is not writable","typeGuard":"function isWriteError(e: unknown): e is Error & { code?: string } {\n  return e instanceof Error && typeof (e as NodeJS.ErrnoException).code === 'string';\n}","tryCatchPattern":"try {\n  await ngCompletionSetup();\n} catch (e: any) {\n  if (e instanceof Error && e.message.startsWith('Failed to append autocompletion setup')) {\n    console.error('Underlying cause:', e.cause); // Node errno (EACCES, EROFS, ...)\n    // fallback: append the source line manually\n  } else { throw e; }\n}","preventionTips":["Verify write permission on your shell RC file before running setup (test -w ~/.bashrc).","Avoid read-only mounts for $HOME in containers.","Watch for ENOSPC (disk full) on machines with little free space.","Know the manual fix: append `source <(ng completion script)` yourself."],"tags":["filesystem","permissions","autocompletion","angular-cli"],"backgroundTag":"file-write-permission-denied","analyzedSha":"bb72145f9ab45aee29f523236b3a25cd0813a841","analyzedAt":"2026-08-30T02:47:34.745Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}