parallax/jsPDF · error · Error

Background index out of range.

Error message

Background index out of range.

What it means

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.

Source

Thrown at src/libs/omggif.js:73

  buf[p++] = 0x47;
  buf[p++] = 0x49;
  buf[p++] = 0x46; // GIF
  buf[p++] = 0x38;
  buf[p++] = 0x39;
  buf[p++] = 0x61; // 89a

  // Handling of Global Color Table (palette) and background index.
  var gp_num_colors_pow2 = 0;
  var background = 0;
  if (global_palette !== null) {
    var gp_num_colors = check_palette_and_num_colors(global_palette);
    while ((gp_num_colors >>= 1)) ++gp_num_colors_pow2;
    gp_num_colors = 1 << gp_num_colors_pow2;
    --gp_num_colors_pow2;
    if (gopts.background !== undefined) {
      background = gopts.background;
      if (background >= gp_num_colors)
        throw new Error("Background index out of range.");
      // The GIF spec states that a background index of 0 should be ignored, so
      // this is probably a mistake and you really want to set it to another
      // slot in the palette.  But actually in the end most browsers, etc end
      // up ignoring this almost completely (including for dispose background).
      if (background === 0)
        throw new Error("Background index explicitly passed as 0.");
    }
  }

  // - Logical Screen Descriptor.
  // NOTE(deanm): w/h apparently ignored by implementations, but set anyway.
  buf[p++] = width & 0xff;
  buf[p++] = (width >> 8) & 0xff;
  buf[p++] = height & 0xff;
  buf[p++] = (height >> 8) & 0xff;
  // NOTE: Indicates 0-bpp original color resolution (unused?).
  buf[p++] = (global_palette !== null ? 0x80 : 0) | gp_num_colors_pow2; // Global Color Table Flag. // NOTE: No sort flag (unused?).
  buf[p++] = background; // Background Color Index.

View on GitHub (pinned to a3930ce03a)

Solutions

1. Ensure 0 <= background < palette.length (and < the padded gp_num_colors).
2. Omit gopts.background entirely if you do not need a background color.
3. Clamp: Math.min(background, palette.length - 1).

Example fix

// before
new GifWriter(buf, w, h, { palette: pal, background: 7 }); // pal.length === 4
// after
var bg = (gopts.background < pal.length) ? gopts.background : pal.length - 1;
new GifWriter(buf, w, h, { palette: pal, background: bg });

if (gopts.background === undefined || gopts.background < pal.length) new GifWriter(buf, w, h, { palette: pal, background: gopts.background });

function isValidBackgroundIndex(idx, palLen){ return typeof idx === 'number' && idx >= 0 && idx < palLen; }

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

When it happens

Trigger: 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.

Common situations: Hardcoding a background index that was valid for a previous palette; deriving background from user selection without bounding it to palette size.

Related errors

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

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