denoland/deno · error · TypeError

Cannot convert a BigInt value to a number

Error message

Cannot convert a BigInt value to a number

What it means

This TypeError comes from Deno's WebIDL conversion layer (ext/webidl/00_webidl.js), used by every web API that takes a numeric argument. When a value must be converted to a WebIDL numeric type (long, double, etc.), the toNumber() helper explicitly rejects bigint so the implicit, lossy BigInt-to-Number conversion cannot happen silently. You hit it by passing a BigInt (e.g. 10n) to any web API number parameter.

Source

Thrown at ext/webidl/00_webidl.js:119

// allocate a fresh `{ __proto__: null }` on every call. Converters only read
// from `opts` -- never mutate -- so a shared frozen object is safe.
const EMPTY_OPTS = ObjectFreeze({ __proto__: null });

function makeException(ErrorType, message, prefix, context, code = undefined) {
  const err = new ErrorType(
    `${prefix ? prefix + ": " : ""}${context ? context : "Value"} ${message}`,
  );
  // Optional Node-compatible error code (e.g. ERR_INVALID_ARG_TYPE) so that
  // node:* consumers observing `err.code` behave the same as on Node.
  if (code !== undefined) {
    err.code = code;
  }
  return err;
}

function toNumber(value) {
  if (typeof value === "bigint") {
    throw new TypeError("Cannot convert a BigInt value to a number");
  }
  return Number(value);
}

function type(V) {
  if (V === null) {
    return "Null";
  }
  switch (typeof V) {
    case "undefined":
      return "Undefined";
    case "boolean":
      return "Boolean";
    case "number":
      return "Number";
    case "string":
      return "String";
    case "symbol":

View on GitHub (pinned to f7822238ca)

Solutions

1. Convert explicitly before the call: Number(bigintValue) (safe if the value fits in a double).
2. For values beyond Number.MAX_SAFE_INTEGER, restructure the API usage — no web API accepts BigInt numerics.
3. Find where the BigInt originated (uint64 parsing, 10n literals) and keep numbers as Number unless precision demands BigInt.
4. Type your boundaries: annotate API-facing fields as number so TypeScript flags BigInt at compile time.

Example fix

// before
const id = 9007199254740993n;
performance.measure("m", { start: Number(id) , duration: BigInt(10) });

// after
const id = 9007199254740993n;
performance.measure("m", { start: Number(id), duration: 10 });

function toWebNumber(v) {
  if (typeof v === "bigint") {
    if (v > BigInt(Number.MAX_SAFE_INTEGER)) {
      throw new RangeError("value loses precision as Number");
    }
    return Number(v);
  }
  return v;
}
performance.measure("m", { start: toWebNumber(startTs) });

function isNotBigInt(v) {
  return typeof v !== "bigint";
}

try { apiCall(value); } catch (e) { if (e instanceof TypeError && e.message.includes("BigInt")) apiCall(Number(value)); else throw e; }

When it happens

Trigger: performance.now()-style timestamps stored as BigInt passed back into an API; API counters from BigInt arithmetic fed into numeric options; crypto or hash outputs (BigInt) passed to numeric parameters; calling web APIs from code that uses BigInt for large IDs.

Common situations: Mixed codebases mixing BigInt (for 64-bit IDs) with web API calls; converting Node Buffer/uint64 values to BigInt and forwarding them; refactors that changed a field from Number to BigInt and broke downstream API calls; JSON.parse producing Numbers while other layers produce BigInts.

Related errors

• Cannot convert a Symbol value to a string
• Value must be a bigint: received ${typeof value}
• Failed to execute 'observe' on 'PerformanceObserver': Cannot
• Failed to execute 'observe' on 'PerformanceObserver': Either
• Failed to execute 'observe' on 'PerformanceObserver': 'entry

AI-assisted analysis of denoland/deno@f7822238ca (2026-08-20). Data as JSON: /api/errors/259f20bea729ca05. Report an issue: GitHub.