paperclipai/paperclip · error

--max-session-list-cost-usd must resolve to at least one cen

Error message

--max-session-list-cost-usd must resolve to at least one cent

What it means

`--max-session-list-cost-usd` must parse to a finite number greater than zero whose USD value rounds to at least one safe-integer cent. `validateManagedAgentSetup` throws this for values like 0, negative numbers, non-numeric strings, Infinity/NaN, or sub-cent amounts that round to 0. This cap guards against unbounded list-cost spend on Managed Agents sessions.

Source

Thrown at cli/src/commands/managed-agent.ts:99

  const model = required(options.model, "--model");
  if (model !== CLAUDE_MANAGED_QUALIFIED_MODEL) {
    throw new Error(
      `--model must be the qualified Managed Agents model ${CLAUDE_MANAGED_QUALIFIED_MODEL}`,
    );
  }
  if (!UUID_RE.test(apiKeySecretId)) {
    throw new Error("--api-key-secret-id must be a UUID");
  }

  const defaultMaxListCostUsd = Number(options.maxSessionListCostUsd);
  const cents = Math.round(defaultMaxListCostUsd * 100);
  if (
    !Number.isFinite(defaultMaxListCostUsd)
    || defaultMaxListCostUsd <= 0
    || !Number.isSafeInteger(cents)
    || cents <= 0
  ) {
    throw new Error("--max-session-list-cost-usd must resolve to at least one cent");
  }

  return {
    anthropicApiKey,
    profileKey,
    displayName,
    apiKeySecretId,
    model,
    agentId: options.agentId?.trim() || undefined,
    agentVersion: options.agentVersion?.trim() || undefined,
    environmentId: options.environmentId?.trim() || undefined,
    defaultMaxListCostUsd,
  };
}

async function anthropicRequest(
  key: string,
  method: "GET" | "POST",

View on GitHub (pinned to 5716fe907e)

Solutions

1. Pass a plain decimal ≥ 0.01, e.g. --max-session-list-cost-usd 5.00
2. Remove currency symbols, commas, and units from the value
3. Check the shell/config variable actually contains a numeric value before invoking
4. If you genuinely need a sub-cent cap, it is not allowed — the minimum is one cent

Example fix

// before
--max-session-list-cost-usd "$MAX_COST"   # MAX_COST=""
// after
MAX_COST="5.00"
--max-session-list-cost-usd "$MAX_COST"

const cost = Number(maxSessionListCostUsd);
const cents = Math.round(cost * 100);
if (!Number.isFinite(cost) || cost <= 0 || !Number.isSafeInteger(cents) || cents <= 0) {
  throw new Error(`max-session-list-cost-usd must be a decimal ≥ 0.01 (got "${maxSessionListCostUsd}")`);
}

try {
  await setupManagedAgent(opts);
} catch (err) {
  if (err instanceof Error && err.message.includes("at least one cent")) {
    console.error("Provide a plain numeric USD amount ≥ 0.01, e.g. 5.00"); process.exitCode = 2;
  } else throw err;
}

When it happens

Trigger: Passing `--max-session-list-cost-usd 0`, `abc`, `-5`, `0.001` (rounds to 0 cents), or an empty value; locale-formatted numbers like "1,50" that Number() cannot parse; passing a value with a currency symbol.

Common situations: Env-var-driven config where the variable is unset and becomes "undefined"; decimal-comma locales; YAML/JSON configs exporting the limit as a string with units ("$5"); typos like 0.004 intending "small but nonzero".

Related errors

• --model must be the qualified Managed Agents model ${CLAUDE_
• --api-key-secret-id must be a UUID
• unknown argument: ${args[index] ?? ""}
• OpenCode test drives require --model openrouter/<model>, wit
• --api-key-env must name a valid environment variable.

AI-assisted analysis of paperclipai/paperclip@5716fe907e (2026-09-02). Data as JSON: /api/errors/3ab332aeeb94f300. Report an issue: GitHub.