parallax/jsPDF · error · Error

Disposal out of range.

Error message

Disposal out of range.

What it means

Thrown by GifWriter.addFrame when opts.disposal is outside 0..3. GIF disposal methods are 0 (unspecified), 1 (do not dispose), 2 (restore to background), 3 (restore to previous); values 4-7 are reserved by the spec and rejected.

Source

Thrown at src/libs/omggif.js:188

    var delay = opts.delay === undefined ? 0 : opts.delay;

    // From the spec:
    //     0 -   No disposal specified. The decoder is
    //           not required to take any action.
    //     1 -   Do not dispose. The graphic is to be left
    //           in place.
    //     2 -   Restore to background color. The area used by the
    //           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;

View on GitHub (pinned to a3930ce03a)

Solutions

1. Map your disposal enum to GIF values 0..3 before addFrame.
2. Omit opts.disposal to use the default 0.
3. Validate disposal is an integer in 0..3.

Example fix

// before
gw.addFrame(x, y, w, h, pixels, { disposal: animEnumRestore }); // animEnumRestore === 4
// after
var gifDisposal = Math.max(0, Math.min(3, animEnumRestore - 1));
gw.addFrame(x, y, w, h, pixels, { disposal: gifDisposal });

function normDisposal(d){ d = d == null ? 0 : Math.floor(d); return d < 0 ? 0 : d > 3 ? 3 : d; }
gw.addFrame(x, y, w, h, pixels, { disposal: normDisposal(opts.disposal) });

function isValidDisposal(v){ return v == null || (Number.isInteger(v) && v >= 0 && v <= 3); }

try { gw.addFrame(x, y, w, h, pixels, opts); } catch (e) { if (/Disposal out of range/.test(e.message)) { opts.disposal = 0; gw.addFrame(x, y, w, h, pixels, opts); } else throw e; }

When it happens

Trigger: Passing { disposal: 4 } or higher; passing a negative disposal; deriving disposal from an enum whose numbering differs from GIF spec values.

Common situations: Using a generic animation disposal enum (some libraries use 1-4 instead of 0-3); defaulting to an out-of-range sentinel.

Related errors

• Loop count invalid.
• x/y invalid.
• Not enough pixels for the frame size.
• Must supply either a local or global palette.
• Transparent color index.

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