lovell/sharp · error · Error

Expected raw.height ${inputOptions.raw.height} to be a multi

Error message

Expected raw.height ${inputOptions.raw.height} to be a multiple of raw.pageHeight ${inputOptions.raw.pageHeight}

What it means

Thrown when raw pixel input specifies a pageHeight that does not evenly divide the total height. Raw multi-page images are represented as a single tall buffer split into equal-sized pages, so height must be an exact multiple of pageHeight; otherwise pages would have unequal sizes and the page boundaries could not be computed. The check is `raw.height % raw.pageHeight !== 0`.

Source

Thrown at lib/input.mjs:236

            inputDescriptor.rawDepth = 'uchar';
            break;
        }
      } else {
        throw new Error('Expected width, height and channels for raw pixel input');
      }
      inputDescriptor.rawPremultiplied = false;
      if (is.defined(inputOptions.raw.premultiplied)) {
        if (is.bool(inputOptions.raw.premultiplied)) {
          inputDescriptor.rawPremultiplied = inputOptions.raw.premultiplied;
        } else {
          throw is.invalidParameterError('raw.premultiplied', 'boolean', inputOptions.raw.premultiplied);
        }
      }
      inputDescriptor.rawPageHeight = 0;
      if (is.defined(inputOptions.raw.pageHeight)) {
        if (is.integer(inputOptions.raw.pageHeight) && inputOptions.raw.pageHeight > 0 && inputOptions.raw.pageHeight <= inputOptions.raw.height) {
          if (inputOptions.raw.height % inputOptions.raw.pageHeight !== 0) {
            throw new Error(`Expected raw.height ${inputOptions.raw.height} to be a multiple of raw.pageHeight ${inputOptions.raw.pageHeight}`);
          }
          inputDescriptor.rawPageHeight = inputOptions.raw.pageHeight;
        } else {
          throw is.invalidParameterError('raw.pageHeight', 'positive integer', inputOptions.raw.pageHeight);
        }
      }
    }
    // Multi-page input (GIF, TIFF, PDF)
    if (is.defined(inputOptions.animated)) {
      if (is.bool(inputOptions.animated)) {
        inputDescriptor.pages = inputOptions.animated ? -1 : 1;
      } else {
        throw is.invalidParameterError('animated', 'boolean', inputOptions.animated);
      }
    }
    if (is.defined(inputOptions.pages)) {
      if (is.integer(inputOptions.pages) && is.inRange(inputOptions.pages, -1, 100000)) {
        inputDescriptor.pages = inputOptions.pages;

View on GitHub (pinned to 56676c6918)

Solutions

1. Choose pageHeight so that height / pageHeight is a whole number (e.g., height 100 with pageHeight 25 yields 4 pages).
2. For a single-page raw image, either omit pageHeight or set it equal to height.
3. Recompute total height as pageHeight * numberOfPages and pass that as height.

Example fix

// before
sharp(buf, { raw: { width: 10, height: 100, channels: 4, pageHeight: 30 } })

// after
sharp(buf, { raw: { width: 10, height: 90, channels: 4, pageHeight: 30 } }) // 3 pages

function rawPages(buffer, { width, pageHeight, pages, channels }) {
  const height = pageHeight * pages;
  if (height % pageHeight !== 0) throw new Error('height must be a multiple of pageHeight');
  if (buffer.length !== width * height * channels) throw new Error('buffer size mismatch');
  return sharp(buffer, { raw: { width, height, channels, pageHeight } });
}

function rawHeightDividesPageHeight(raw) {
  return Number.isInteger(raw.height) && Number.isInteger(raw.pageHeight) && raw.height % raw.pageHeight === 0;
}

When it happens

Trigger: sharp(buf, { raw: { width: 10, height: 100, channels: 4, pageHeight: 30 } }) — 100 is not divisible by 30. Setting pageHeight to a value larger than height also fails earlier with a different error; this specific error is for the in-range but non-divisor case.

Common situations: Treating a single-page buffer as multi-page by guessing pageHeight. Mismatch between the actual frame height of an animation and the declared total height. Using pageHeight equal to height for a single page (valid, 1 page) vs an arbitrary value.

Related errors

• Expected create.height ${inputOptions.create.height} to be a
• Expected width, height and channels for raw pixel input
• Invalid input
• Recursive join is unsupported
• Expected at least two images to join

AI-assisted analysis of lovell/sharp@56676c6918 (2026-08-13). Data as JSON: /api/errors/938dd2fbc80ccb25. Report an issue: GitHub.