paperclipai/paperclip · error

Invalid ${label}: ${value}

Error message

Invalid ${label}: ${value}

What it means

Thrown by parsePositiveInt() in the pipelines CLI when a numeric flag value cannot be parsed as a positive integer. It is a user-input validation guard used for --expected-version and --lease-seconds options before they are sent to the API. The error interpolates the offending label and raw value so the operator can see which flag was wrong.

Source

Thrown at cli/src/commands/pipelines.ts:713

  } catch (error) {
    throw new Error(`Invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
  }
}

function asObject(value: unknown): JsonObject {
  if (!value || typeof value !== "object" || Array.isArray(value)) {
    throw new Error("Expected a JSON object.");
  }
  return value as JsonObject;
}

function asOptionalObject(value: unknown): JsonObject | undefined {
  return value && typeof value === "object" && !Array.isArray(value) ? value as JsonObject : undefined;
}

function parsePositiveInt(value: string, label: string): number {
  const parsed = Number(value);
  if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`Invalid ${label}: ${value}`);
  return parsed;
}

function parseCsv(value: string): string[] {
  return value.split(",").map((item) => item.trim()).filter(Boolean);
}

function setIfDefined(target: JsonObject, key: string, value: unknown): void {
  if (value !== undefined) target[key] = value;
}

function looksLikeUuid(value: string): boolean {
  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 exactlyOneFlag(first: boolean | undefined, second: boolean | undefined, firstName: string, secondName: string): string {
  if (Boolean(first) === Boolean(second)) throw new Error(`Pass exactly one of ${firstName} or ${secondName}.`);
  return first ? firstName : secondName;

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Re-run the command with a positive integer for the named flag (e.g. `--expected-version 3`, `--lease-seconds 60`).
2. If the value comes from a shell variable, ensure it is set and numeric: `--expected-version "${EXPECTED_VERSION:?must be set}"`.
3. If you intended an unset/optional value, omit the flag entirely instead of passing 0 or empty.

Example fix

// before
paperclipai pipelines checkout <id> --lease-seconds 0
// after
paperclipai pipelines checkout <id> --lease-seconds 60

function positiveInt(v: string, label: string): number {
  const n = Number(v);
  if (!Number.isInteger(n) || n <= 0) {
    throw new Error(`Invalid ${label}: ${v}`);
  }
  return n;
}
// call before the API: const version = positiveInt(opts.expectedVersion, "expected version");

function isPositiveIntString(v: unknown): v is string {
  return typeof v === "string" && Number.isInteger(Number(v)) && Number(v) > 0;
}

When it happens

Trigger: Calling `paperclipai pipelines ... --expected-version <v>` or `--lease-seconds <n>` where the value fails `Number.isInteger(parsed) || parsed <= 0`. Concrete producers: `--expected-version 0`, `--lease-seconds -5`, `--expected-version 3.5`, `--lease-seconds abc`, or omitting a value so commander passes an empty string.

Common situations: Operators typing a version ordinal that is zero or negative, passing a decimal version like `2.1`, or copy-pasting a value with whitespace/units. Also triggered when a wrapper script passes an unset shell variable that expands to empty.

Related errors

• Pass exactly one of ${firstName} or ${secondName}.
• Pass exactly one of --approve, --reject, or --request-change
• --lines must be a positive integer.
• --payload must be a JSON object
• ${name} must be a JSON object

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