lovell/sharp · error · Error

Expected width, height and channels for raw pixel input

Error message

Expected width, height and channels for raw pixel input

What it means

Thrown when raw pixel input is requested (inputOptions.raw is defined) but the raw descriptor is missing width, height, or channels. Raw input means sharp must interpret a flat byte buffer as an image, so it needs all three dimensions to decode the bytes correctly; without them the buffer length is ambiguous. The error fires in the else branch after the per-field validations.

Source

Thrown at lib/input.mjs:222

            break;
          case Uint32Array:
            inputDescriptor.rawDepth = 'uint';
            break;
          case Int32Array:
            inputDescriptor.rawDepth = 'int';
            break;
          case Float32Array:
            inputDescriptor.rawDepth = 'float';
            break;
          case Float64Array:
            inputDescriptor.rawDepth = 'double';
            break;
          default:
            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);

View on GitHub (pinned to 56676c6918)

Solutions

1. Always provide all three: raw: { width, height, channels } where channels is 1-4.
2. Verify channels matches the buffer layout (RGBA = 4, RGB = 3, grayscale = 1).
3. Assert buffer.length === width * height * channels before calling sharp to catch mismatches early.

Example fix

// before
sharp(rgbaBuffer, { raw: { width: 100, height: 100 } })

// after
sharp(rgbaBuffer, { raw: { width: 100, height: 100, channels: 4 } })

function rawInput(buffer, { width, height, channels }) {
  if (!Number.isInteger(width) || !Number.isInteger(height) || ![1,2,3,4].includes(channels)) {
    throw new Error('raw requires integer width, height, and channels (1-4)');
  }
  if (buffer.length !== width * height * channels) {
    throw new Error(`raw buffer length ${buffer.length} != width*height*channels (${width*height*channels})`);
  }
  return sharp(buffer, { raw: { width, height, channels } });
}

function isCompleteRawSpec(raw) {
  return raw && Number.isInteger(raw.width) && Number.isInteger(raw.height) && Number.isInteger(raw.channels);
}

When it happens

Trigger: Calling sharp(buffer, { raw: { width: 100, height: 100 } }) with channels omitted, or any combination missing one of the three. Passing raw: {} with no fields. Providing width and channels but forgetting height.

Common situations: Adapting canvas/webgl pixel data (which provides Uint8ClampedArray) where the developer forgets channels: 4 for RGBA. Feeding a raw buffer from a sensor or decoder without propagating dimensions. Copying a raw example and deleting a field by accident.

Related errors

• Expected raw.height ${inputOptions.raw.height} to be a multi
• Expected valid width, height and channels to create a new in
• 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/e321a11baa967c95. Report an issue: GitHub.