paperclipai/paperclip · error · Error

Invalid --ttl-days value: ${opts.ttlDays}

Error message

Invalid --ttl-days value: ${opts.ttlDays}

What it means

Thrown by resolveBoardKeyExpiresAt (token.ts:240) when --ttl-days is provided but Number(value) is NaN, Infinity, or <= 0. Guards against non-positive or unparseable TTL values being sent to the board key creation endpoint.

Source

Thrown at cli/src/commands/client/token.ts:240

    if (!agent || agent.companyId !== companyId) throw new Error(`Agent not found: ${agentRef}`);
    return agent;
  }
  const query = new URLSearchParams({ companyId });
  const agent = await api.get<Agent>(`${apiPath`/api/agents/${trimmed}`}?${query.toString()}`);
  if (!agent || agent.companyId !== companyId) throw new Error(`Agent not found: ${agentRef}`);
  return agent;
}

function resolveBoardKeyExpiresAt(opts: BoardTokenOptions): Date | null | undefined {
  if (opts.neverExpires) return null;
  if (opts.expiresAt?.trim()) {
    const date = new Date(opts.expiresAt.trim());
    if (!Number.isFinite(date.getTime())) throw new Error(`Invalid --expires-at value: ${opts.expiresAt}`);
    return date;
  }
  if (opts.ttlDays?.trim()) {
    const days = Number(opts.ttlDays);
    if (!Number.isFinite(days) || days <= 0) throw new Error(`Invalid --ttl-days value: ${opts.ttlDays}`);
    return new Date(Date.now() + Math.floor(days * 24 * 60 * 60 * 1000));
  }
  return undefined;
}

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Pass a positive integer number of days: --ttl-days 30.
2. Strip any unit suffix before passing.
3. For permanent keys, use --never-expires instead of a large TTL.

Example fix

// before
--ttl-days "30d"
// after
--ttl-days 30

function isValidTtlDays(value: string | undefined): boolean {
  if (!value?.trim()) return false;
  const n = Number(value);
  return Number.isFinite(n) && n > 0;
}

if (opts.ttlDays && !isValidTtlDays(opts.ttlDays)) {
  console.error(`--ttl-days "${opts.ttlDays}" must be a positive number.`);
  process.exit(1);
}

function isPositiveNumber(value: string): boolean {
  const n = Number(value);
  return Number.isFinite(n) && n > 0;
}

When it happens

Trigger: Passing --ttl-days "abc", --ttl-days "0", --ttl-days "-5", or --ttl-days "". Number() coerces and the guard rejects anything that is not a finite positive numeric value.

Common situations: Passing an env var that expanded empty, a decimal like 1.5 (Number.isFinite passes but intent is days), or a stray unit suffix like "7d".

Related errors

• Invalid --expires-at value: ${opts.expiresAt}
• Invalid --adapter-override "${raw}". Use slug=type.
• Invalid ${flag} "${raw}". Use ${format}.
• Failed to create board API key
• Agent reference is required

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