paperclipai/paperclip · error · Error

Refusing to modify non-regular shell rc file ${rcPath}.

Error message

Refusing to modify non-regular shell rc file ${rcPath}.

What it means

Thrown by addManagedPathBlock when the target shell rc file (e.g., ~/.bashrc, ~/.zshrc) exists but is not a regular file or is a symbolic link. Before appending the managed PATH export block, the installer verifies the rc file is a plain, user-owned file to prevent writing through symlinks or to special files, which could corrupt user environments or write to unintended locations.

Source

Thrown at cli/src/install-store.ts:428

    fs.rmSync(paths.shimPath, { force: true });
    return true;
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT") return true;
    throw error;
  }
}

export function managedPathBlock(): string {
  return `${PATH_BLOCK_START}\nexport PATH="$HOME/.local/bin:$PATH"\n${PATH_BLOCK_END}`;
}

export function addManagedPathBlock(rcPath: string): boolean {
  let existing = "";
  let mode = 0o600;
  try {
    const stat = fs.lstatSync(rcPath);
    if (!stat.isFile() || stat.isSymbolicLink()) {
      throw new Error(`Refusing to modify non-regular shell rc file ${rcPath}.`);
    }
    assertOwnedByCurrentUser(stat, rcPath);
    mode = stat.mode & 0o777;
    existing = fs.readFileSync(rcPath, "utf8");
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
  }
  if (existing.includes(PATH_BLOCK_START)) return false;
  fs.mkdirSync(path.dirname(rcPath), { recursive: true });
  const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
  writeFileAtomic(rcPath, `${existing}${prefix}${managedPathBlock()}\n`, mode);
  return true;
}

export function removeManagedPathBlock(rcPath: string): boolean {
  let existing: string;
  let mode: number;
  try {

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Inspect the rc file: 'ls -la ~/.bashrc' (or the relevant rc path) to confirm its type.
2. If it is a symlink to a real config file, resolve the target and either point the installer at the real file or replace the symlink with a regular file.
3. If using a dotfile manager, add the PATH export block manually to the managed source file.
4. Alternatively, set the PATH manually: 'export PATH="$HOME/.local/bin:$PATH"' in your shell config.

Example fix

// before: ~/.bashrc is a symlink managed by chezmoi
// ls -la ~/.bashrc -> lrwxrwxrwx -> ~/.local/share/chezmoi/dot_bashrc

// after: add the PATH block to the real source file instead
// echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.local/share/chezmoi/dot_bashrc
// chezmoi apply

import fs from 'node:fs';

function isSafeRcFile(rcPath: string): boolean {
  try {
    const stat = fs.lstatSync(rcPath);
    return stat.isFile() && !stat.isSymbolicLink();
  } catch (error) {
    return (error as NodeJS.ErrnoException).code === 'ENOENT';
  }
}

// Call before addManagedPathBlock:
if (!isSafeRcFile(rcPath)) {
  console.warn(`Shell rc file ${rcPath} is a symlink or non-regular file; skipping PATH block.`);
  // Manually add: export PATH="$HOME/.local/bin:$PATH"
}

try {
  addManagedPathBlock(rcPath);
} catch (error) {
  if (error instanceof Error && error.message.includes('non-regular shell rc file')) {
    // rc file is symlinked (e.g., dotfile manager); add PATH manually to the source
    console.warn(`Add manually: export PATH=\"$HOME/.local/bin:$PATH\" to ${rcPath}'s real target`);
  } else {
    throw error;
  }
}

When it happens

Trigger: Calling addManagedPathBlock(rcPath) where rcPath exists but is a symlink, directory, socket, or other non-regular file. This typically happens during 'paperclipai install' when it tries to add the PATH block to shell rc files.

Common situations: A dotfile manager (e.g., stow, chezmoi) symlinks ~/.bashrc to a managed source file. The rc file is symlinked to a shared/network location. A user accidentally created ~/.bashrc as a directory.

Related errors

• Refusing to use non-directory install-store path ${directory
• Refusing to modify path not owned by the current user: ${tar
• Refusing to use unsafe install-store marker ${paths.markerPa
• Refusing to use unrecognized install store ${paths.cliRoot}.
• Refusing to remove unsafe install-store path ${paths.cliRoot

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/38af71133f796e4c. Report an issue: GitHub.