What causes "${label} must be an integer between 1 and ${maximum}." in paperclipai/paperclip?

Set the field to a positive integer within its cap: maxIterations 1–8, maxOutputTokens 1–4096, timeoutSeconds 1–300.

${label} must be an integer between 1 and ${maximum}.

Error message

${label} must be an integer between 1 and ${maximum}.

What it means

boundedLimit validates AWS AgentCore numeric limits in the Codex adapter config UI. A value must be absent/empty (fallback applied) or a positive safe integer not exceeding the per-field maximum (maxIterations ≤ 8, maxOutputTokens ≤ 4096, timeoutSeconds ≤ 300). Anything else — strings, floats, zero, negatives, over-max — throws with a labeled message naming the field and bound.

Source

Thrown at packages/adapters/codex-local/src/ui/build-config.ts:132

  );
  const managedAgentsRetentionAcknowledged =
    schemaValues.managedAgentsRetentionAcknowledged === true;
  const agentCoreRetentionAcknowledged =
    schemaValues.agentCoreRetentionAcknowledged === true;
  const boundedLimit = (
    value: unknown,
    fallback: number,
    maximum: number,
    label: string,
  ) => {
    if (value === undefined || value === null || value === "") return fallback;
    if (
      typeof value !== "number"
      || !Number.isSafeInteger(value)
      || value <= 0
      || value > maximum
    ) {
      throw new Error(`${label} must be an integer between 1 and ${maximum}.`);
    }
    return value;
  };
  const maxIterations = boundedLimit(
    schemaValues.maxIterations,
    8,
    8,
    "AWS AgentCore maxIterations",
  );
  const maxOutputTokens = boundedLimit(
    schemaValues.maxOutputTokens,
    4_096,
    4_096,
    "AWS AgentCore maxOutputTokens",
  );
  const timeoutSeconds = boundedLimit(
    schemaValues.timeoutSeconds,
    300,

View on GitHub (pinned to 01ad858492)

Solutions

Set the field to a positive integer within its cap: maxIterations 1–8, maxOutputTokens 1–4096, timeoutSeconds 1–300.
Clear the field (undefined/null/empty string) to accept the built-in fallback (8 / 4096 / 300).
Coerce form input with Number(...) and Number.isInteger before saving config.
If you need higher limits, raise them in the adapter code — the caps are enforced client-side by design.

Example fix

// before
config.timeoutSeconds = "600";      // string, over cap
// after
config.timeoutSeconds = 300;        // positive integer within max 300 (or omit for default)

Defensive patterns

Strategy: validation

Validate before calling

function bounded(value, max) {
  if (value === undefined || value === null || value === "") return null; // use fallback
  const n = Number(value);
  if (!Number.isSafeInteger(n) || n <= 0 || n > max) {
    throw new RangeError(`expected integer 1..${max}, got ${JSON.stringify(value)}`);
  }
  return n;
}
bounded(form.maxIterations, 8);
bounded(form.maxOutputTokens, 4096);
bounded(form.timeoutSeconds, 300);

Type guard

function isBoundedInt(v: unknown, max: number): v is number {
  return typeof v === "number" && Number.isSafeInteger(v) && v > 0 && v <= max;
}

Try / catch

try {
  const config = buildConfig(rawValues);
} catch (e) {
  if (e instanceof Error && e.message.includes("must be an integer between 1 and")) {
    showFormError(e.message); // surface field-level message in the UI, keep other fields
  } else throw e;
}

Prevention

Use <input type="number" min="1" max="{cap}" step="1"> for these fields.
Coerce form values with Number() before persisting config.
Remember the caps: maxIterations 8, maxOutputTokens 4096, timeoutSeconds 300.
Leave fields empty to get defaults (8 / 4096 / 300) instead of entering 0.

When it happens

Trigger: Saving adapter config where schemaValues.maxIterations, maxOutputTokens, or timeoutSeconds is a non-number (e.g. "8" as a string from a form), a float (250.5), 0, negative, or above the cap (e.g. timeoutSeconds: 600, maxIterations: 12).

Common situations: Form inputs returning strings instead of numbers; pasting tuning values from AgentCore docs that exceed Paperclip's tighter caps; JSON hand-edits with decimal or negative values; forgetting to clear a field so it stays "" is fine, but whitespace or 0 is not.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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