{"record":{"id":"1737336d0a64e0d1","repo":"tursodatabase/turso","slug":"bigint-value-is-outside-sqlite-s-signed-64-bit-int","errorCode":null,"errorMessage":"BigInt value is outside SQLite's signed 64-bit integer range","messagePattern":"BigInt value is outside SQLite's signed 64-bit integer range","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"bindings/javascript/packages/common/promise.ts","lineNumber":922,"sourceCode":"        throw attachRollbackError(err, rollbackError);\n      }\n    }\n    throw err;\n  }\n  return results;\n}\n\nfunction normalizeBatchBindValue(value: any): any {\n  if (value === null || value === undefined) return null;\n  if (typeof value === \"number\") {\n    if (!Number.isFinite(value)) {\n      throw new TypeError(\"Only finite numbers (not Infinity or NaN) can be passed as arguments\");\n    }\n    return value;\n  }\n  if (typeof value === \"bigint\") {\n    if (value < -(1n << 63n) || value > (1n << 63n) - 1n) {\n      throw new TypeError(\"BigInt value is outside SQLite's signed 64-bit integer range\");\n    }\n    return value;\n  }\n  if (\n    typeof value === \"boolean\" ||\n    typeof value === \"string\" ||\n    (ArrayBuffer.isView(value) && !(value instanceof DataView))\n  ) {\n    return value;\n  }\n  if (value instanceof ArrayBuffer) return new Uint8Array(value);\n  return String(value);\n}\n\n/**\n * A handle to an open transaction, passed as the first argument to the\n * callback of `Database.transactionAsync()`. All SQL of the transaction\n * must go through this handle: the transaction wrapper holds the database's","sourceCodeStart":904,"sourceCodeEnd":940,"githubUrl":"https://github.com/tursodatabase/turso/blob/c1e59287258d99b309e362a63f48822256e2f65f/bindings/javascript/packages/common/promise.ts#L904-L940","documentation":"SQLite integers are signed 64-bit (-2^63 .. 2^63-1). The JS driver checks bigint bind values against this range in normalizeBatchBindValue and throws a TypeError when the value would overflow, because an out-of-range integer cannot round-trip through SQLite without corruption or silent truncation.","triggerScenarios":"Passing a BigInt bind parameter to db.batch() whose value is < -(2n**63n) or > 2n**63n - 1n, e.g. 2n**63n or -9223372036854775809n.","commonSituations":"Computing hashes, UUIDv7-like IDs, or crypto-derived numbers into BigInt and binding them directly; multiplying large counters; reading an unsigned u64 from another system (Rust/Go) and passing it through.","solutions":["Range-check the value before binding and clamp or wrap it into the signed 64-bit range.","Bind as TEXT (value.toString()) if the value must be preserved exactly.","Redesign the schema column to hold the value as TEXT or split across two columns.","Use Number if the magnitude fits in a double and losslessness is acceptable (still <= 2^53)."],"exampleFix":"// before\nconst id = 18446744073709551615n; // u64 max\nstmt.bind(id); // throws\n// after\nstmt.bind(id <= 9223372036854775807n ? id : id.toString());","handlingStrategy":"validation","validationCode":"const MIN = -(2n**63n), MAX = 2n**63n - 1n;\nif (args.some(a => typeof a === 'bigint' && (a < MIN || a > MAX))) throw new RangeError('bigint out of i64 range');","typeGuard":"const isI64 = (v: bigint): boolean => v >= -(2n**63n) && v <= 2n**63n - 1n;","tryCatchPattern":"try { await db.batch(stmts); } catch (e) { if (e instanceof TypeError && /signed 64-bit/.test(e.message)) { /* rebind as string or clamp */ } else throw e; }","preventionTips":["Always BigInt.asIntN(64, v) values coming from u64 sources.","Store oversized integers as TEXT by design, not by exception.","Add a shared toSqlBigInt() helper that validates or throws early.","Test the boundary values ±(2**63-1), ±2**63 in your suite."],"tags":["javascript","bigint","bind-parameters"],"backgroundTag":"bigint-out-of-range","analyzedSha":"c1e59287258d99b309e362a63f48822256e2f65f","analyzedAt":"2026-08-31T11:17:35.598Z","contentChangedAt":"2026-08-31T11:17:35.598Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}