paperclipai/paperclip · error · PaperclipRunnerProviderProfileError

paperclip_runner_aws_agentcore_spend_cap_invalid

paperclip_runner_aws_agentcore_spend_cap_invalid

Error message

The AWS AgentCore profile requires a positive estimated session spend ceiling.

What it means

AWS AgentCore runs require a positive estimated session cost ceiling (maxEstimatedSessionCostUsd), resolved from the adapter profile override or the stored configuration's defaultMaxEstimatedSessionCostUsd via positiveNumberOrNull. positiveNumberOrNull itself throws this same error when the stored default is present but not a positive finite number; a second throw fires when both sources are absent (null). This enforces the budget hard-stop invariant for AgentCore sessions.

Source

Thrown at server/src/services/native-runtime/provider-profile.ts:574

          `The qualified AWS AgentCore profile is missing ${key}.`,
        );
      }
      return value;
    };
    if (remote.eventExpiryDays !== 90) {
      throw new PaperclipRunnerProviderProfileError(
        "paperclip_runner_aws_agentcore_retention_unqualified",
        "The qualified AWS AgentCore profile must retain Memory events for exactly 90 days.",
      );
    }
    const maxEstimatedSessionCostUsd = profile.maxEstimatedSessionCostUsd
      ?? positiveNumberOrNull(
        remote.defaultMaxEstimatedSessionCostUsd,
        "paperclip_runner_aws_agentcore_spend_cap_invalid",
        "The AWS AgentCore profile requires a positive estimated session spend ceiling.",
      );
    if (maxEstimatedSessionCostUsd === null) {
      throw new PaperclipRunnerProviderProfileError(
        "paperclip_runner_aws_agentcore_spend_cap_invalid",
        "The AWS AgentCore profile requires a positive estimated session spend ceiling.",
      );
    }
    const model = profile.model ?? required("defaultModel");
    if (model !== AGENTCORE_QUALIFIED_MODEL) {
      throw new PaperclipRunnerProviderProfileError(
        "paperclip_runner_aws_agentcore_model_unqualified",
        `The AWS AgentCore profile requires exact model ${AGENTCORE_QUALIFIED_MODEL}.`,
      );
    }
    return {
      provider: "aws_agentcore",
      model,
      agentCoreProfile: {
        profileId: stored.id,
        region: required("region"),
        accountId: required("accountId"),

View on GitHub (pinned to 01ad858492)

Solutions

1. Set maxEstimatedSessionCostUsd in the adapter profile config to a positive finite number (e.g. 20).
2. Set stored.configuration.defaultMaxEstimatedSessionCostUsd to a positive number so runs inherit a default.
3. Fix the stored value's type — it must be a JSON number, not a string, and greater than 0.
4. Re-run the AgentCore qualification flow so the spend default is written as part of qualification.

Example fix

// before (stored configuration)
{ "defaultMaxEstimatedSessionCostUsd": 0, ... }
// after
{ "defaultMaxEstimatedSessionCostUsd": 20, ... }

const cap = profile.maxEstimatedSessionCostUsd ?? storedProfile.configuration?.defaultMaxEstimatedSessionCostUsd;
if (!(typeof cap === "number" && Number.isFinite(cap) && cap > 0)) {
  throw new Error("Set a positive maxEstimatedSessionCostUsd (or defaultMaxEstimatedSessionCostUsd) before running aws_agentcore");
}

const isPositiveUsd = (v: unknown): v is number =>
  typeof v === "number" && Number.isFinite(v) && v > 0;

try {
  await executeRun(run);
} catch (e) {
  if (e instanceof PaperclipRunnerProviderProfileError && e.code === "paperclip_runner_aws_agentcore_spend_cap_invalid") {
    await agentCoreProfileService.updateConfiguration(profileId, { defaultMaxEstimatedSessionCostUsd: 20 });
    return executeRun(run);
  }
  throw e;
}

When it happens

Trigger: provider=aws_agentcore run where profile.maxEstimatedSessionCostUsd is unset and stored.configuration.defaultMaxEstimatedSessionCostUsd is either absent (first throw at line 568) or set to 0, negative, or a non-numeric value (throw from positiveNumberOrNull at line 562-565).

Common situations: A qualified profile stored without a spend default; a run config setting maxEstimatedSessionCostUsd: 0 to mean 'unlimited'; a configuration edit that wrote the ceiling as a string like "20.00".

Related errors

• paperclip_runner_claude_managed_spend_cap_invalid
• paperclip_runner_aws_agentcore_profile_mismatch
• paperclip_runner_aws_agentcore_profile_invalid
• paperclip_runner_aws_agentcore_retention_unqualified
• OpenCode evals require exact version 1.18.17; received ${ver

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-02). Data as JSON: /api/errors/8057f53809f3e388. Report an issue: GitHub.