paperclipai/paperclip · error · Error

Invalid --collision value. Use: rename, skip, replace

Error message

Invalid --collision value. Use: rename, skip, replace

What it means

Thrown when `opts.collision` (defaulted to "rename", lowercased) is not one of 'rename', 'skip', 'replace'. This validates the --collision flag that controls how the import reconciles name collisions with existing companies. The check runs before any network call.

Source

Thrown at cli/src/commands/client/company.ts:1672

      .option("--yes", "Accept default selection and skip the pre-import confirmation prompt", false)
      .option("--dry-run", "Run preview only without applying", false)
      .action(async (fromPathOrUrl: string, opts: CompanyImportOptions) => {
        try {
          if (!opts.apiBase?.trim() && opts.paperclipUrl?.trim()) {
            opts.apiBase = opts.paperclipUrl.trim();
          }
          const ctx = resolveCommandContext(opts);
          const interactiveView = isInteractiveTerminal() && !ctx.json;
          const from = fromPathOrUrl.trim();
          if (!from) {
            throw new Error("Source path or URL is required.");
          }

          const include = resolveImportInclude(opts.include);
          const agents = parseAgents(opts.agents);
          const collision = (opts.collision ?? "rename").toLowerCase() as CompanyCollisionMode;
          if (!["rename", "skip", "replace"].includes(collision)) {
            throw new Error("Invalid --collision value. Use: rename, skip, replace");
          }

          const inferredTarget = opts.target ?? (opts.companyId || ctx.companyId ? "existing" : "new");
          const target = inferredTarget.toLowerCase() as CompanyImportTargetMode;
          if (!["new", "existing"].includes(target)) {
            throw new Error("Invalid --target value. Use: new | existing");
          }

          const existingTargetCompanyId = opts.companyId?.trim() || ctx.companyId;
          const targetPayload =
            target === "existing"
              ? {
                  mode: "existing_company" as const,
                  companyId: existingTargetCompanyId,
                }
              : {
                  mode: "new_company" as const,
                  newCompanyName: opts.newCompanyName?.trim() || null,

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Use exactly one of: `--collision rename`, `--collision skip`, or `--collision replace`.
2. Run `paperclipai company import --help` to confirm the accepted values.
3. If the value comes from a variable, validate it against the allow-list before the CLI call.

Example fix

// before
const collision = process.env.COLLISION ?? "overwrite";
// after
const allowed = ["rename", "skip", "replace"] as const;
const collision = allowed.includes(process.env.COLLISION as any) ? process.env.COLLISION : "rename";

const COLLISION_MODES = ["rename", "skip", "replace"] as const;
type CollisionMode = typeof COLLISION_MODES[number];
function normalizeCollision(v: string | undefined): CollisionMode {
  const lower = (v ?? "rename").trim().toLowerCase();
  if (!COLLISION_MODES.includes(lower as CollisionMode)) {
    throw new Error(`Invalid collision mode '${v}'; expected one of ${COLLISION_MODES.join(", ")}`);
  }
  return lower as CollisionMode;
}

function isCollisionMode(v: unknown): v is "rename" | "skip" | "replace" {
  return typeof v === "string" && ["rename", "skip", "replace"].includes(v.toLowerCase());
}

When it happens

Trigger: Passing `--collision overwrite`, `--collision merge`, or any typo like `--collision renam`; passing a value from an env var or config that was misspelled.

Common situations: Developer guesses a flag value instead of checking `--help`; a script copies a flag value from a different tool's vocabulary (overwrite/merge); tab-completion or shell history inserting a wrong token.

Related errors

• Invalid --target value. Use: new | existing
• Source path or URL is required.
• Target existing company requires --company-id (or context de
• Only GitHub URLs and local paths are supported for import. G
• --ref is only supported for GitHub import sources.

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