parallax/jsPDF · warning · Error

Background index explicitly passed as 0.

Error message

Background index explicitly passed as 0.

What it means

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.)

Source

Thrown at src/libs/omggif.js:79

  // 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.
  buf[p++] = 0; // Pixel aspect ratio (unused?).

  // - Global Color Table
  if (global_palette !== null) {
    for (var i = 0, il = global_palette.length; i < il; ++i) {
      var rgb = global_palette[i];

View on GitHub (pinned to a3930ce03a)

Solutions

1. Omit gopts.background (or set to undefined) when you want no/ignored background.
2. If you genuinely want index 0 behavior, you cannot pass it; rely on the default 0 by not setting the field.
3. Use a sentinel and only set background when the user picks a non-zero slot.

Example fix

// before
var gopts = { palette: pal, background: selectedBg }; // selectedBg === 0
// after
var gopts = { palette: pal };
if (selectedBg > 0) gopts.background = selectedBg;

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

function isNonZeroBackground(gopts){ return gopts.background === undefined || gopts.background > 0; }

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

When it happens

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

Common situations: 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.

Related errors

• Background index out of range.
• 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/2089a3e22e36c830. Report an issue: GitHub.