ruvnet/ruflo · error · Error

${label} exceeds unsigned 64-bit range

Error message

${label} exceeds unsigned 64-bit range

What it means

parseCanonicalUnsigned() enforces a 64-bit ceiling: values that match the canonical decimal grammar but exceed 2^64-1 throw '<label> exceeds unsigned 64-bit range'. The cap keeps ids/versions safely representable across languages and wire formats.

Source

Thrown at v3/@claude-flow/codex/src/harness/unsigned-integer.ts:11

const CANONICAL_UNSIGNED = /^(?:0|[1-9][0-9]*)$/;
const MAX_UNSIGNED_64 = (1n << 64n) - 1n;

/** Parse a decimal unsigned integer without accepting aliases such as +1, 01, hex, or whitespace. */
export function parseCanonicalUnsigned(value: string, label: string): bigint {
  if (!CANONICAL_UNSIGNED.test(value)) {
    throw new Error(`${label} must be a canonical unsigned decimal integer`);
  }
  const parsed = BigInt(value);
  if (parsed > MAX_UNSIGNED_64) {
    throw new Error(`${label} exceeds unsigned 64-bit range`);
  }
  return parsed;
}

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Identify the field via the label and fix the generator to stay within uint64
2. Use a different id scheme (hex string uuid) for values that legitimately exceed 2^64-1
3. Validate your inputs against the same ceiling before sending (BigInt(value) > (1n<<64n)-1n)

Example fix

// before
version: String(Number.MAX_SAFE_INTEGER * 1000); // ~9e18*1e3 > 2^64-1? no; use explicit example
version: '340282366920938463463374607431768211455'; // 2^128-1 -> throws
// after
const MAX = (1n << 64n) - 1n;
version: (BigInt(counter) & MAX).toString();

const MAX_U64 = (1n << 64n) - 1n;
function withinU64(v: string): boolean {
  return /^(?:0|[1-9][0-9]*)$/.test(v) && BigInt(v) <= MAX_U64;
}

const MAX_U64 = (1n << 64n) - 1n;
function isU64String(v: unknown): v is string {
  return typeof v === 'string' && /^(?:0|[1-9][0-9]*)$/.test(v) && BigInt(v) <= MAX_U64;
}

try { parseCanonicalUnsigned(value, label); } catch (e) { if (/exceeds unsigned 64-bit/.test(String(e))) throw new RangeError(`${label} out of range`); throw e; }

When it happens

Trigger: Passing a lease version or sequence like '18446744073709551616' (2^64) or larger — e.g. timestamps-in-nanoseconds far in the future, ids derived from random 128-bit values, or corrupted/garbage numeric strings.

Common situations: Generators use Date.now()*1e6 or uuid-derived integers; upstream systems send 128-bit ids; fuzzing feeds huge strings into protocol fields.

Related errors

• ${label} must be a canonical unsigned decimal integer
• Validation failed: ${result.error}
• FORBIDDEN_PROTOCOL
• Rating must be integer 1-5
• localCompute: no adapter for graphId=${input.graphId}

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/78cb1952aeff4ed9. Report an issue: GitHub.