{"record":{"id":"2d7a56ff650344f0","repo":"oven-sh/bun","slug":"invalid-vlq-data-at-index-i-text","errorCode":null,"errorMessage":"Invalid VLQ data at index ${i}: ${text}","messagePattern":"Invalid VLQ data at index (.+?): (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/bun-error/sourcemap.ts","lineNumber":51,"sourceCode":"\n// ripped from https://github.com/evanw/source-map-visualization/blob/gh-pages/code.js#L179\nexport function decodeMappings(mappings, sourcesCount) {\n  const n = mappings.length;\n  let data = new Int32Array(1024);\n  let dataLength = 0;\n  let generatedLine = 0;\n  let generatedLineStart = 0;\n  let generatedColumn = 0;\n  let originalSource = 0;\n  let originalLine = 0;\n  let originalColumn = 0;\n  let originalName = 0;\n  let needToSortGeneratedColumns = false;\n  let i = 0;\n\n  function decodeError(text) {\n    const error = `Invalid VLQ data at index ${i}: ${text}`;\n    throw new Error(error);\n  }\n\n  function decodeVLQ() {\n    let shift = 0;\n    let vlq = 0;\n\n    // Scan over the input\n    while (true) {\n      // Read a byte\n      if (i >= mappings.length) decodeError(\"Expected extra data\");\n      const c = mappings.charCodeAt(i);\n      if ((c & 0x7f) !== c) decodeError(\"Invalid character\");\n      const index = vlqTable[c & 0x7f];\n      if (index === 0xff) decodeError(\"Invalid character\");\n      i++;\n\n      // Decode the byte\n      vlq |= (index & 31) << shift;","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/oven-sh/bun/blob/8c5296ac459e8252d3cd702f3fbcbb0c249d95d5/packages/bun-error/sourcemap.ts#L33-L69","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Regenerate the source map with a standard tool rather than editing the mappings string","If you post-process maps, parse and re-serialize with a source-map library instead of string manipulation","Catch this error and fall back to showing the un-mapped (generated) positions so a bad map does not break error rendering","Inspect mappings at the reported index to confirm where corruption begins"],"exampleFix":"// before\nconst map = parseSourceMap(JSON.parse(jsonText)); // malformed VLQ throws\n\n// after\nlet map;\ntry {\n  map = parseSourceMap(JSON.parse(jsonText));\n} catch (err) {\n  if (!(err instanceof Error && err.message.startsWith('Invalid VLQ data'))) throw err;\n  map = undefined; // fall back to un-mapped stack frames\n}","handlingStrategy":"try-catch","validationCode":"// cheap pre-check: VLQ alphabet plus segment separators\nconst mappingsOk = typeof json.mappings === 'string' && /^[A-Za-z0-9+/,;]*$/.test(json.mappings);\nif (!mappingsOk) throw new TypeError('mappings contains characters outside the VLQ alphabet');","typeGuard":null,"tryCatchPattern":"try {\n  const map = parseSourceMap(json);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Invalid VLQ data')) {\n    // corrupt mappings: degrade to un-mapped positions rather than crashing rendering\n    return rawPositions;\n  }\n  throw err;\n}","preventionTips":["Treat .map files as binary artifacts: never regex/string-edit them","Verify checksums/sizes when transferring maps between systems","Wrap map parsing so one corrupt file cannot break error rendering"],"tags":["sourcemap","vlq","parsing","corruption"],"backgroundTag":null,"analyzedSha":"8c5296ac459e8252d3cd702f3fbcbb0c249d95d5","analyzedAt":"2026-08-16T08:01:58.794Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}