parallax/jsPDF · error · Error

An unknown error occurred whilst processing the image.

Error message

An unknown error occurred whilst processing the image.

What it means

After calling the format-specific processor (e.g., processPNG, processJPEG), processImageData checks that the result is truthy. A falsy return indicates the processor encountered an internal failure but did not throw — typically because the image data was valid enough to pass format detection but corrupt or incomplete at a deeper level. This is a catch-all guard against silently embedding broken image data into the PDF.

Source

Thrown at src/modules/addimage.js:914

    if (!result) {
      // no need to convert if imageData is already uint8array
      if (!(imageData instanceof Uint8Array) && format !== "RGBA") {
        dataAsBinaryString = imageData;
        imageData = binaryStringToUint8Array(imageData);
      }

      result = this["process" + format.toUpperCase()](
        imageData,
        getImageIndex.call(this),
        alias,
        checkCompressValue(compression),
        dataAsBinaryString
      );
    }

    if (!result) {
      throw new Error("An unknown error occurred whilst processing the image.");
    }
    return result;
  };

  /**
   * @name convertBase64ToBinaryString
   * @function
   * @param {string} stringData
   * @returns {string} binary string
   */
  var convertBase64ToBinaryString = (jsPDFAPI.__addimage__.convertBase64ToBinaryString = function(
    stringData,
    throwError
  ) {
    throwError = typeof throwError === "boolean" ? throwError : true;
    var imageData = "";
    var rawData;

View on GitHub (pinned to a3930ce03a)

Solutions

Validate the image data before passing it to addImage: try opening it in an image viewer or using a validation library
Check that the base64/binary data is complete and not truncated: verify the data length matches expectations
Re-fetch or re-encode the image data from the source
If building a custom processor, ensure it always returns a valid image object or throws a descriptive error

Example fix

// before - truncated PNG data passes magic bytes but fails processing
doc.addImage(truncatedBase64, 'PNG', 10, 10); // throws 'unknown error'

// after - validate completeness first
var binary = atob(base64String);
if (binary.length < MIN_PNG_SIZE) throw new Error('Image data too small');
doc.addImage(binary, 'PNG', 10, 10);

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate image data integrity before processing
function isValidImageData(data, format) {
  if (!data) return false;
  if (typeof data === 'string') return data.length > 0;
  if (data instanceof Uint8Array) return data.length > 100; // minimum header size
  return true;
}

if (isValidImageData(imageData, format)) {
  doc.addImage(imageData, format, 10, 10);
}

Try / catch

try {
  doc.addImage(imageData, format, 10, 10);
} catch (e) {
  if (e.message.includes('unknown error occurred whilst processing')) {
    // Image data is corrupt or incomplete
    console.error('Image processing failed - data may be corrupt');
    // Re-fetch or use alternative image source
  } else throw e;
}

Prevention

Verify image data completeness before passing to addImage
Handle network fetch errors that produce truncated data
Test image data in an image viewer or validator before embedding in PDF

When it happens

Trigger: Passing truncated or corrupt image data that passes magic-byte detection but fails during decoding. Passing image data with correct headers but invalid body content. Memory issues causing the processor to return without completing. A bug in a custom image processor that returns undefined.

Common situations: Fetching images over unreliable networks where the response is truncated. Processing user-uploaded files that are partially written. Base64 strings that were corrupted during transmission. Using a format processor that has a version-specific bug.

Related errors

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