paperclipai/paperclip · error · Error

Invalid ${flag} "${raw}". Use ${format}.

Error message

Invalid ${flag} "${raw}". Use ${format}.

What it means

Generic key=value parser error thrown by parseKeyValueOption in teams.ts. Fires when the input contains no '=' separator or the '=' is the first character (indexOf('=') <= 0), making a key unrecoverable. Used as the shared parser behind flags like --adapter-override.

Source

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

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

function parseKeyValueOption(raw: string, flag: string, format: string): [string, string] {
  const separator = raw.indexOf("=");
  if (separator <= 0) {
    throw new Error(`Invalid ${flag} "${raw}". Use ${format}.`);
  }
  return [raw.slice(0, separator).trim(), raw.slice(separator + 1).trim()];
}

function removeUndefined<T extends Record<string, unknown>>(input: T): T {
  return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined)) as T;
}

function emptyStringToUndefined(value: string | undefined): string | undefined {
  const trimmed = value?.trim();
  return trimmed || undefined;
}

function collectOptionValue(value: string, previous: string[]): string[] {
  return [...previous, value];
}

function appendQueryParam(params: URLSearchParams, key: string, value: string | undefined): void {

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Add the '=' separator exactly once, e.g. slug=type.
2. Quote the argument so the shell does not split it: --adapter-override "slug=type".
3. Check the flag's documented format in the error message and match it character-for-character.

Example fix

// before
--adapter-override codex
// after
--adapter-override "codex=claude"

function parseKeyValue(raw: string, flag: string, format: string): [string, string] | null {
  const sep = raw.indexOf("=");
  if (sep <= 0) {
    console.error(`Invalid ${flag} "${raw}". Use ${format}.`);
    return null;
  }
  return [raw.slice(0, sep).trim(), raw.slice(sep + 1).trim()];
}

function hasKeyValueSeparator(raw: string): boolean {
  const sep = raw.indexOf("=");
  return sep > 0;
}

When it happens

Trigger: Passing `--adapter-override codex` (no '='), `--adapter-override "=value"` (leading '='), or any key=value flag value where the separator is missing or leading. The format hint passed in (--adapter-override → slug=type) is interpolated into the message.

Common situations: Using ':' or '-' instead of '=', a shell that swallowed the '=', or a value that was meant to be quoted but got split by the shell into separate argv entries.

Related errors

• Invalid --adapter-override "${raw}". Use slug=type.
• Agent reference is required
• Invalid --expires-at value: ${opts.expiresAt}
• Invalid --ttl-days value: ${opts.ttlDays}
• workspaceId is required for update

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