oven-sh/bun · error · Error

Invalid VLQ data at index ${i}: ${text}

Error message

Invalid VLQ data at index ${i}: ${text}

What it means

While decoding the mappings VLQ stream, the parser hit a byte sequence it cannot consume: 'Expected extra data' when the string ends mid-value, 'Invalid character' for bytes outside the base64 VLQ alphabet, etc. The index reported is the cursor position in the mappings string where decoding stopped, which usually marks the truncation or corruption point.

Source

Thrown at packages/bun-error/sourcemap.ts:51

// ripped from https://github.com/evanw/source-map-visualization/blob/gh-pages/code.js#L179
export function decodeMappings(mappings, sourcesCount) {
  const n = mappings.length;
  let data = new Int32Array(1024);
  let dataLength = 0;
  let generatedLine = 0;
  let generatedLineStart = 0;
  let generatedColumn = 0;
  let originalSource = 0;
  let originalLine = 0;
  let originalColumn = 0;
  let originalName = 0;
  let needToSortGeneratedColumns = false;
  let i = 0;

  function decodeError(text) {
    const error = `Invalid VLQ data at index ${i}: ${text}`;
    throw new Error(error);
  }

  function decodeVLQ() {
    let shift = 0;
    let vlq = 0;

    // Scan over the input
    while (true) {
      // Read a byte
      if (i >= mappings.length) decodeError("Expected extra data");
      const c = mappings.charCodeAt(i);
      if ((c & 0x7f) !== c) decodeError("Invalid character");
      const index = vlqTable[c & 0x7f];
      if (index === 0xff) decodeError("Invalid character");
      i++;

      // Decode the byte
      vlq |= (index & 31) << shift;

View on GitHub (pinned to 8c5296ac45)

Solutions

1. Regenerate the source map with a standard tool rather than editing the mappings string
2. If you post-process maps, parse and re-serialize with a source-map library instead of string manipulation
3. Catch this error and fall back to showing the un-mapped (generated) positions so a bad map does not break error rendering
4. Inspect mappings at the reported index to confirm where corruption begins

Example fix

// before
const map = parseSourceMap(JSON.parse(jsonText)); // malformed VLQ throws

// after
let map;
try {
  map = parseSourceMap(JSON.parse(jsonText));
} catch (err) {
  if (!(err instanceof Error && err.message.startsWith('Invalid VLQ data'))) throw err;
  map = undefined; // fall back to un-mapped stack frames
}

// cheap pre-check: VLQ alphabet plus segment separators
const mappingsOk = typeof json.mappings === 'string' && /^[A-Za-z0-9+/,;]*$/.test(json.mappings);
if (!mappingsOk) throw new TypeError('mappings contains characters outside the VLQ alphabet');

try {
  const map = parseSourceMap(json);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Invalid VLQ data')) {
    // corrupt mappings: degrade to un-mapped positions rather than crashing rendering
    return rawPositions;
  }
  throw err;
}

When it happens

Trigger: A truncated mappings string (cut off mid-VLQ), regex/string surgery on mappings that removed or inserted characters, invalid characters like '-', '.', '=' padding, or concatenating segment strings without proper ',' / ';' separators.

Common situations: Maps mangled by text-processing pipelines; partial writes of .map files (disk full, interrupted build); custom map emitters with off-by-one VLQ encoding; maps transferred through systems that strip characters.

Related errors

• picsum ${p.id}: ${res.status}
• ${runtime} client exited ${code}${code === null ? " (timed o
• Invalid source map
• not 200
• Expected ${receivedCount[0]} to equal ${sentCount}

AI-assisted analysis of oven-sh/bun@8c5296ac45 (2026-08-16). Data as JSON: /api/errors/2d7a56ff650344f0. Report an issue: GitHub.