{"record":{"id":"c35dbb4877332601","repo":"parallax/jsPDF","slug":"background-index-out-of-range","errorCode":null,"errorMessage":"Background index out of range.","messagePattern":"Background index out of range\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/libs/omggif.js","lineNumber":73,"sourceCode":"  buf[p++] = 0x47;\n  buf[p++] = 0x49;\n  buf[p++] = 0x46; // GIF\n  buf[p++] = 0x38;\n  buf[p++] = 0x39;\n  buf[p++] = 0x61; // 89a\n\n  // Handling of Global Color Table (palette) and background index.\n  var gp_num_colors_pow2 = 0;\n  var background = 0;\n  if (global_palette !== null) {\n    var gp_num_colors = check_palette_and_num_colors(global_palette);\n    while ((gp_num_colors >>= 1)) ++gp_num_colors_pow2;\n    gp_num_colors = 1 << gp_num_colors_pow2;\n    --gp_num_colors_pow2;\n    if (gopts.background !== undefined) {\n      background = gopts.background;\n      if (background >= gp_num_colors)\n        throw new Error(\"Background index out of range.\");\n      // The GIF spec states that a background index of 0 should be ignored, so\n      // this is probably a mistake and you really want to set it to another\n      // slot in the palette.  But actually in the end most browsers, etc end\n      // up ignoring this almost completely (including for dispose background).\n      if (background === 0)\n        throw new Error(\"Background index explicitly passed as 0.\");\n    }\n  }\n\n  // - Logical Screen Descriptor.\n  // NOTE(deanm): w/h apparently ignored by implementations, but set anyway.\n  buf[p++] = width & 0xff;\n  buf[p++] = (width >> 8) & 0xff;\n  buf[p++] = height & 0xff;\n  buf[p++] = (height >> 8) & 0xff;\n  // NOTE: Indicates 0-bpp original color resolution (unused?).\n  buf[p++] = (global_palette !== null ? 0x80 : 0) | gp_num_colors_pow2; // Global Color Table Flag. // NOTE: No sort flag (unused?).\n  buf[p++] = background; // Background Color Index.","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/parallax/jsPDF/blob/a3930ce03a585a26b2c76d12a0f413ce96f6d1a3/src/libs/omggif.js#L55-L91","documentation":"Thrown by GifWriter when gopts.background is defined and is >= the number of colors in the global palette (gp_num_colors). The background index must reference an existing slot in the palette, otherwise the GIF would point at a non-existent color.","triggerScenarios":"Passing { background: 5 } with a 4-color palette; passing a background index computed from a larger palette than the one supplied; zero-based index confusion where background is set to palette length.","commonSituations":"Hardcoding a background index that was valid for a previous palette; deriving background from user selection without bounding it to palette size.","solutions":["Ensure 0 <= background < palette.length (and < the padded gp_num_colors).","Omit gopts.background entirely if you do not need a background color.","Clamp: Math.min(background, palette.length - 1)."],"exampleFix":"// before\nnew GifWriter(buf, w, h, { palette: pal, background: 7 }); // pal.length === 4\n// after\nvar bg = (gopts.background < pal.length) ? gopts.background : pal.length - 1;\nnew GifWriter(buf, w, h, { palette: pal, background: bg });","handlingStrategy":"validation","validationCode":"if (gopts.background === undefined || gopts.background < pal.length) new GifWriter(buf, w, h, { palette: pal, background: gopts.background });","typeGuard":"function isValidBackgroundIndex(idx, palLen){ return typeof idx === 'number' && idx >= 0 && idx < palLen; }","tryCatchPattern":"try { new GifWriter(buf, w, h, gopts); } catch (e) { if (/Background index out of range/.test(e.message)) { delete gopts.background; new GifWriter(buf, w, h, gopts); } else throw e; }","preventionTips":["Bound background index to palette length","Omit background when not needed"],"tags":["gif","omggif","image","palette","validation","index"],"backgroundTag":null,"analyzedSha":"a3930ce03a585a26b2c76d12a0f413ce96f6d1a3","analyzedAt":"2026-08-13T05:33:39.648Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}