JuliusBrussee/caveman · error · Error

MCP config path contains dangling symlink ${ancestor}; refus

Error message

MCP config path contains dangling symlink ${ancestor}; refusing mutation

What it means

Guard inside canonicalMcpConfigPath: while walking the path's ancestors to resolve it to a canonical real path, an ancestor exists as a symbolic link but realpathSync failed on it, meaning the link is dangling (points to a nonexistent target). Writing through it could create files in unexpected places, so mutation is refused.

Source

Thrown at packages/cli/src/index.ts:10866

  agent: "kilo" | "qwen";
  path: string;
  before: Buffer | null;
  beforeMode: number;
  after: Buffer | null;
  changed: boolean;
};

function canonicalMcpConfigPath(path: string): string {
  const absolute = normalize(resolve(path));
  const missing: string[] = [];
  let ancestor = absolute;
  while (true) {
    try {
      return normalize(join(realpathSync(ancestor), ...missing));
    } catch {
      try {
        if (lstatSync(ancestor).isSymbolicLink()) {
          throw new Error(`MCP config path contains dangling symlink ${ancestor}; refusing mutation`);
        }
      } catch (error) {
        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
      }
      const parent = dirname(ancestor);
      if (parent === ancestor) return absolute;
      missing.unshift(basename(ancestor));
      ancestor = parent;
    }
  }
}

function ownedMcpConfigPlan(
  agent: "kilo" | "qwen",
  path: string,
  loaded: { bytes: Buffer | null; exists: boolean },
  after: Buffer | null,
): OwnedMcpConfigPlan {

View on GitHub (pinned to 5184b3d11a)

Solutions

1. Fix or remove the dangling symlink named in the message so it points to an existing target
2. Repoint the MCP config location (KILO_CONFIG_DIR, XDG_CONFIG_HOME, or the agent's config path) to a real directory
3. Create the symlink's target directory if it was intended to exist

When it happens

Trigger: Thrown at packages/cli/src/index.ts:10866 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of JuliusBrussee/caveman@5184b3d11a (2026-09-06). Data as JSON: /api/errors/51eb5606b8c9f2c3. Report an issue: GitHub.