paperclipai/paperclip · error · Error

Invalid --name-override "${raw}". Use slug=name.

Error message

Invalid --name-override "${raw}". Use slug=name.

What it means

Thrown by parseNameOverrides() when a --name-override value, after splitting on '=' and trimming, yields an empty slug or empty name. Used by `teams preview` and `teams install` to rename imported agents. Note parseKeyValueOption itself throws a different message when there is no '=' at all; this throw is specifically for a '=' present but a blank side (e.g. 'slug=' or whitespace-only slug).

Source

Thrown at cli/src/commands/client/teams.ts:480

  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
}

function buildSourcePolicy(opts: TeamPreviewOptions): CatalogTeamSourcePolicy | undefined {
  const sourcePolicy = removeUndefined({
    allowExternalSources: opts.allowExternalSources || undefined,
    allowUnpinnedOptionalSources: opts.allowUnpinnedOptionalSources || undefined,
    allowLocalPathSources: opts.allowLocalPathSources || undefined,
  });
  return Object.keys(sourcePolicy).length > 0 ? sourcePolicy : undefined;
}

function parseNameOverrides(values: string[] | undefined): Record<string, string> | undefined {
  if (!values || values.length === 0) return undefined;
  const result: Record<string, string> = {};
  for (const raw of values) {
    const [slug, name] = parseKeyValueOption(raw, "--name-override", "slug=name");
    if (!slug || !name) {
      throw new Error(`Invalid --name-override "${raw}". Use slug=name.`);
    }
    result[slug] = name;
  }
  return result;
}

function parseSecretValues(values: string[] | undefined): Record<string, string> | undefined {
  if (!values || values.length === 0) return undefined;
  const result: Record<string, string> = {};
  for (const raw of values) {
    const [key, value] = parseKeyValueOption(raw, "--secret-value", "key=value");
    if (!key) {
      throw new Error(`Invalid --secret-value "${raw}". Use key=value.`);
    }
    result[key] = value;
  }
  return result;
}

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Format as `--name-override <slug>=<name>` with both sides non-empty, e.g. `--name-override reviewer=SeniorReviewer`.
2. Confirm the slug matches an agent slug declared by the catalog team.
3. If scripting, validate each entry matches /^[^=]+=[^=]+$/ and that both trimmed halves are non-empty.

Example fix

# before
paperclipai teams install <ref> --name-override reviewer=
# after
paperclipai teams install <ref> --name-override reviewer=SeniorReviewer

function validNameOverride(v: string): boolean {
  const i = v.indexOf("=");
  if (i <= 0) return false;
  const slug = v.slice(0, i).trim();
  const name = v.slice(i + 1).trim();
  return slug.length > 0 && name.length > 0;
}
for (const v of nameOverrides) {
  if (!validNameOverride(v)) throw new Error(`Bad --name-override "${v}". Use slug=name.`);
}

function isNameOverride(v: string): boolean {
  const i = v.indexOf("=");
  return i > 0 && v.slice(0, i).trim().length > 0 && v.slice(i + 1).trim().length > 0;
}

When it happens

Trigger: Passing `--name-override slug=` (empty new name), `--name-override =Name` (empty slug — though this may trip the parseKeyValueOption guard first), or a value whose slug side is only whitespace.

Common situations: Typing the flag without the new name, misordered arguments, or a generated command that emits an empty value pair.

Related errors

• Invalid --secret-value "${raw}". Use key=value.
• Invalid JSON: ${err instanceof Error ? err.message : String(
• Company ID is required.
• Catalog team reference is required.
• --payload must be a JSON object

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