paperclipai/paperclip · error · Error

${path} must be a positive safe integer

Error message

${path} must be a positive safe integer

What it means

The positiveInteger() helper validates that a value is a safe integer greater than zero, using Number.isSafeInteger plus a >0 check, and throws '<path> must be a positive safe integer' otherwise. Applied to numeric fields parsed by parseAgentCoreProfile and parseEvalSessionRequest.

Source

Thrown at packages/paperclip-runner/src/cli/eval-session-contract.ts:110

}

function object(value: unknown, path: string): Record<string, unknown> {
  if (typeof value !== "object" || value === null || Array.isArray(value)) {
    throw new Error(`${path} must be an object`);
  }
  return value as Record<string, unknown>;
}

function text(value: unknown, path: string): string {
  if (typeof value !== "string" || value.trim().length === 0) {
    throw new Error(`${path} must be a non-empty string`);
  }
  return value;
}

function positiveInteger(value: unknown, path: string): number {
  if (!Number.isSafeInteger(value) || Number(value) <= 0) {
    throw new Error(`${path} must be a positive safe integer`);
  }
  return Number(value);
}

export function expectedEvalSessionDriver(
  provider: EvalSessionProvider,
): EvalSessionDriver {
  return provider === "opencode"
    ? "opencode_server"
    : provider === "claude_managed"
      ? "claude_managed_agents_api"
      : provider === "aws_agentcore"
        ? "aws_agentcore_harness_api"
    : provider === "acpx" ? "acpx_runtime" : "codex_app_server";
}

function positiveNumber(value: unknown, path: string): number {
  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {

View on GitHub (pinned to 01ad858492)

Solutions

1. Send the value as an actual JS number that is an integer >= 1
2. If the value is a string, convert with Number() and validate before passing
3. For very large identifiers, keep them as strings in the contract instead of numbers
4. Fix default initialization so unset counters do not fall back to 0

Example fix

// before
const req = { schema: SCHEMA, provider: 'codex', timeoutSeconds: '30' };
// after
const req = { schema: SCHEMA, provider: 'codex', timeoutSeconds: 30 };

function isPositiveSafeInt(v) {
  return Number.isSafeInteger(v) && v > 0;
}
if (!isPositiveSafeInt(payload.count)) throw new Error('count must be a positive safe integer');

function isPositiveSafeInteger(v) {
  return typeof v === 'number' && Number.isSafeInteger(v) && v > 0;
}

try {
  const request = parseEvalSessionRequest(raw);
} catch (err) {
  if (err.message.includes('must be a positive safe integer')) {
    throw new RequestValidationError('Numeric field out of range or wrong type — send an integer >= 1 as a number', { cause: err });
  }
  throw err;
}

When it happens

Trigger: A numeric field validated with positiveInteger() is 0, negative, a float, NaN, a numeric string, or an integer beyond Number.MAX_SAFE_INTEGER (e.g. large int64 values sent as JSON numbers).

Common situations: Limits/counts default to 0 when unset; a caller sends a string like "5" from JSON config; an upstream 64-bit id exceeds the safe-integer range and should be transported as a string instead.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• ${path} must be a positive finite number
• ${path} must be an object
• ${path} must be a non-empty string
• request.managedProfile.betaVersion is not qualified
• request.managedProfile.agentVersion must be a canonical posi

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