{"record":{"id":"dd83dfec24357a17","repo":"parallax/jsPDF","slug":"transparent-color-index","errorCode":null,"errorMessage":"Transparent color index.","messagePattern":"Transparent color index\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/libs/omggif.js","lineNumber":196,"sourceCode":"    //           graphic must be restored to the background color.\n    //     3 -   Restore to previous. The decoder is required to\n    //           restore the area overwritten by the graphic with\n    //           what was there prior to rendering the graphic.\n    //  4-7 -    To be defined.\n    // NOTE(deanm): Dispose background doesn't really work, apparently most\n    // browsers ignore the background palette index and clear to transparency.\n    var disposal = opts.disposal === undefined ? 0 : opts.disposal;\n    if (disposal < 0 || disposal > 3)\n      // 4-7 is reserved.\n      throw new Error(\"Disposal out of range.\");\n\n    var use_transparency = false;\n    var transparent_index = 0;\n    if (opts.transparent !== undefined && opts.transparent !== null) {\n      use_transparency = true;\n      transparent_index = opts.transparent;\n      if (transparent_index < 0 || transparent_index >= num_colors)\n        throw new Error(\"Transparent color index.\");\n    }\n\n    if (disposal !== 0 || use_transparency || delay !== 0) {\n      // - Graphics Control Extension\n      buf[p++] = 0x21;\n      buf[p++] = 0xf9; // Extension / Label.\n      buf[p++] = 4; // Byte size.\n\n      buf[p++] = (disposal << 2) | (use_transparency === true ? 1 : 0);\n      buf[p++] = delay & 0xff;\n      buf[p++] = (delay >> 8) & 0xff;\n      buf[p++] = transparent_index; // Transparent color index.\n      buf[p++] = 0; // Block Terminator.\n    }\n\n    // - Image Descriptor\n    buf[p++] = 0x2c; // Image Seperator.\n    buf[p++] = x & 0xff;","sourceCodeStart":178,"sourceCodeEnd":214,"githubUrl":"https://github.com/parallax/jsPDF/blob/a3930ce03a585a26b2c76d12a0f413ce96f6d1a3/src/libs/omggif.js#L178-L214","documentation":"Thrown by GifWriter.addFrame when opts.transparent is set and the transparent_index is < 0 or >= num_colors (the frame's effective palette size). The transparent color index must point at a valid palette entry so decoders can mask that color.","triggerScenarios":"Passing { transparent: 10 } with a 4-color frame palette; passing a negative index; reusing a transparent index from a larger palette.","commonSituations":"Hardcoding a transparent index valid for one palette but applied to a smaller frame palette; off-by-one using palette length as the index.","solutions":["Ensure 0 <= transparent_index < palette length (and < num_colors after padding).","Omit opts.transparent when transparency is not needed.","Clamp the transparent index to palette size - 1 or recompute it after quantization."],"exampleFix":"// before\ngw.addFrame(x, y, w, h, pixels, { palette: pal, transparent: 9 }); // pal.length === 4\n// after\nvar t = (opts.transparent < pal.length) ? opts.transparent : pal.length - 1;\ngw.addFrame(x, y, w, h, pixels, { palette: pal, transparent: t });","handlingStrategy":"validation","validationCode":"function normTransparent(t, palLen){ return (t == null) ? null : (t < 0 ? 0 : t >= palLen ? palLen-1 : t); }\nif (normTransparent(opts.transparent, pal.length) !== null) opts.transparent = normTransparent(opts.transparent, pal.length);","typeGuard":"function isValidTransparentIndex(t, palLen){ return t == null || (Number.isInteger(t) && t >= 0 && t < palLen); }","tryCatchPattern":"try { gw.addFrame(x, y, w, h, pixels, opts); } catch (e) { if (/Transparent color index/.test(e.message)) { delete opts.transparent; gw.addFrame(x, y, w, h, pixels, opts); } else throw e; }","preventionTips":["Bound transparent index to palette size","Recompute transparent index after quantization"],"tags":["gif","omggif","image","animation","palette","validation","index"],"backgroundTag":null,"analyzedSha":"a3930ce03a585a26b2c76d12a0f413ce96f6d1a3","analyzedAt":"2026-08-13T05:33:39.648Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}