{"record":{"id":"2089a3e22e36c830","repo":"parallax/jsPDF","slug":"background-index-explicitly-passed-as-0","errorCode":null,"errorMessage":"Background index explicitly passed as 0.","messagePattern":"Background index explicitly passed as 0\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"warning","filePath":"src/libs/omggif.js","lineNumber":79,"sourceCode":"\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.\n  buf[p++] = 0; // Pixel aspect ratio (unused?).\n\n  // - Global Color Table\n  if (global_palette !== null) {\n    for (var i = 0, il = global_palette.length; i < il; ++i) {\n      var rgb = global_palette[i];","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/parallax/jsPDF/blob/a3930ce03a585a26b2c76d12a0f413ce96f6d1a3/src/libs/omggif.js#L61-L97","documentation":"Thrown by GifWriter when gopts.background is explicitly passed as 0. The GIF spec states a background index of 0 is ignored by most decoders, so omggif treats passing 0 as a likely mistake and rejects it, nudging the author to pick a meaningful slot. (To use index 0 you must omit background entirely, since 0 is the default.)","triggerScenarios":"Passing { background: 0 } explicitly; a UI whose default selection is the first color and serializes 0; logic that always sets background even when it equals 0.","commonSituations":"Auto-assigning background from a dropdown that defaults to the first palette entry; porting code that defaulted background to 0 as a 'no background' marker.","solutions":["Omit gopts.background (or set to undefined) when you want no/ignored background.","If you genuinely want index 0 behavior, you cannot pass it; rely on the default 0 by not setting the field.","Use a sentinel and only set background when the user picks a non-zero slot."],"exampleFix":"// before\nvar gopts = { palette: pal, background: selectedBg }; // selectedBg === 0\n// after\nvar gopts = { palette: pal };\nif (selectedBg > 0) gopts.background = selectedBg;","handlingStrategy":"validation","validationCode":"if (gopts.background !== 0) { new GifWriter(buf, w, h, gopts); } else { var g = Object.assign({}, gopts); delete g.background; new GifWriter(buf, w, h, g); }","typeGuard":"function isNonZeroBackground(gopts){ return gopts.background === undefined || gopts.background > 0; }","tryCatchPattern":"try { new GifWriter(buf, w, h, gopts); } catch (e) { if (/Background index explicitly passed as 0/.test(e.message)) { delete gopts.background; new GifWriter(buf, w, h, gopts); } else throw e; }","preventionTips":["Treat background 0 as 'unset' and omit the field","Avoid defaulting selection indices to 0"],"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"}