parallax/jsPDF · error · Error

Transparent color index.

Error message

Transparent color index.

What it means

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.

Source

Thrown at src/libs/omggif.js:196

    //           graphic must be restored to the background color.
    //     3 -   Restore to previous. The decoder is required to
    //           restore the area overwritten by the graphic with
    //           what was there prior to rendering the graphic.
    //  4-7 -    To be defined.
    // NOTE(deanm): Dispose background doesn't really work, apparently most
    // browsers ignore the background palette index and clear to transparency.
    var disposal = opts.disposal === undefined ? 0 : opts.disposal;
    if (disposal < 0 || disposal > 3)
      // 4-7 is reserved.
      throw new Error("Disposal out of range.");

    var use_transparency = false;
    var transparent_index = 0;
    if (opts.transparent !== undefined && opts.transparent !== null) {
      use_transparency = true;
      transparent_index = opts.transparent;
      if (transparent_index < 0 || transparent_index >= num_colors)
        throw new Error("Transparent color index.");
    }

    if (disposal !== 0 || use_transparency || delay !== 0) {
      // - Graphics Control Extension
      buf[p++] = 0x21;
      buf[p++] = 0xf9; // Extension / Label.
      buf[p++] = 4; // Byte size.

      buf[p++] = (disposal << 2) | (use_transparency === true ? 1 : 0);
      buf[p++] = delay & 0xff;
      buf[p++] = (delay >> 8) & 0xff;
      buf[p++] = transparent_index; // Transparent color index.
      buf[p++] = 0; // Block Terminator.
    }

    // - Image Descriptor
    buf[p++] = 0x2c; // Image Seperator.
    buf[p++] = x & 0xff;

View on GitHub (pinned to a3930ce03a)

Solutions

1. Ensure 0 <= transparent_index < palette length (and < num_colors after padding).
2. Omit opts.transparent when transparency is not needed.
3. Clamp the transparent index to palette size - 1 or recompute it after quantization.

Example fix

// before
gw.addFrame(x, y, w, h, pixels, { palette: pal, transparent: 9 }); // pal.length === 4
// after
var t = (opts.transparent < pal.length) ? opts.transparent : pal.length - 1;
gw.addFrame(x, y, w, h, pixels, { palette: pal, transparent: t });

function normTransparent(t, palLen){ return (t == null) ? null : (t < 0 ? 0 : t >= palLen ? palLen-1 : t); }
if (normTransparent(opts.transparent, pal.length) !== null) opts.transparent = normTransparent(opts.transparent, pal.length);

function isValidTransparentIndex(t, palLen){ return t == null || (Number.isInteger(t) && t >= 0 && t < palLen); }

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; }

When it happens

Trigger: Passing { transparent: 10 } with a 4-color frame palette; passing a negative index; reusing a transparent index from a larger palette.

Common situations: Hardcoding a transparent index valid for one palette but applied to a smaller frame palette; off-by-one using palette length as the index.

Related errors

• Background index out of range.
• Background index explicitly passed as 0.
• Must supply either a local or global palette.
• Invalid code/color length, must be power of 2 and 2 .. 256.
• Loop count invalid.

AI-assisted analysis of parallax/jsPDF@a3930ce03a (2026-08-13). Data as JSON: /api/errors/dd83dfec24357a17. Report an issue: GitHub.