lovell/sharp · error · Error

Invalid input

Error message

Invalid input

What it means

Thrown by the Sharp constructor when it is invoked with exactly one argument that is not a defined value (undefined or null). The factory guards this up front because every downstream input path (file path, Buffer, Stream, raw pixel data) requires a concrete input; an undefined sole argument almost always indicates a variable that was never assigned. Note arguments.length === 1 is the discriminator, so sharp() with no args is allowed (creates a stream-based pipeline) but sharp(undefined) is not.

Source

Thrown at lib/constructor.mjs:227

 * @param {string} [options.join.valign='top'] - vertical alignment style for images joined vertically (`'top'`, `'centre'`, `'center'`, `'bottom'`).
 * @param {Object} [options.tiff] - Describes TIFF specific options.
 * @param {number} [options.tiff.subifd=-1] - Sub Image File Directory to extract for OME-TIFF, defaults to main image.
 * @param {Object} [options.svg] - Describes SVG specific options.
 * @param {string} [options.svg.stylesheet] - Custom CSS for SVG input, applied with a User Origin during the CSS cascade.
 * @param {boolean} [options.svg.highBitdepth=false] - Set to `true` to render SVG input at 32-bits per channel (128-bit) instead of 8-bits per channel (32-bit) RGBA.
 * @param {Object} [options.pdf] - Describes PDF specific options. Requires the use of a globally-installed libvips compiled with support for PDFium, Poppler, ImageMagick or GraphicsMagick.
 * @param {string|Object} [options.pdf.background] - Background colour to use when PDF is partially transparent. Parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha.
 * @param {Object} [options.openSlide] - Describes OpenSlide specific options. Requires the use of a globally-installed libvips compiled with support for OpenSlide.
 * @param {number} [options.openSlide.level=0] - Level to extract from a multi-level input, zero based.
 * @param {Object} [options.jp2] - Describes JPEG 2000 specific options. Requires the use of a globally-installed libvips compiled with support for OpenJPEG.
 * @param {boolean} [options.jp2.oneshot=false] - Set to `true` to decode tiled JPEG 2000 images in a single operation, improving compatibility.
 * @returns {Sharp}
 * @throws {Error} Invalid parameters
 */
const Sharp = function (input, options) {
  // biome-ignore lint/complexity/noArguments: constructor factory
  if (arguments.length === 1 && !is.defined(input)) {
    throw new Error('Invalid input');
  }
  if (!(this instanceof Sharp)) {
    return new Sharp(input, options);
  }
  stream.Duplex.call(this);
  this.options = {
    // resize options
    topOffsetPre: -1,
    leftOffsetPre: -1,
    widthPre: -1,
    heightPre: -1,
    topOffsetPost: -1,
    leftOffsetPost: -1,
    widthPost: -1,
    heightPost: -1,
    width: -1,
    height: -1,
    canvas: 'crop',

View on GitHub (pinned to 56676c6918)

Solutions

1. Ensure the first argument is a real input: a file path string, a Buffer, a Stream, a Uint8Array, or an array of images to join.
2. If you genuinely want a stream-based pipeline with no initial input, call sharp() with zero arguments.
3. When passing options, use the second parameter: sharp(input, options), never sharp(options).
4. Add a guard before construction: if (!input) throw new Error('input required'); to fail with your own message.

Example fix

// before
const img = sharp(req.body.path); // path is undefined

// after
const path = req.body.path;
if (!path) throw new Error('image path required');
const img = sharp(path);

function sharpSafe(input, options) {
  if (arguments.length >= 1 && (input === undefined || input === null)) {
    throw new Error('sharp: input is required (pass a path, Buffer, Stream, or array)');
  }
  return sharp(input, options);
}

function isValidSharpInput(input) {
  return typeof input === 'string' || Buffer.isBuffer(input) || input instanceof Uint8Array ||
    (typeof input === 'object' && input !== null && typeof input.pipe === 'function') ||
    Array.isArray(input);
}

When it happens

Trigger: Calling sharp(undefined), sharp(null), or sharp(someVariable) where someVariable was never assigned. Passing options as the first arg by mistake: sharp({ density: 72 }) instead of sharp(input, { density: 72 }). Destructuring a missing field: const { path } = req.body; sharp(path) where path is undefined.

Common situations: Form/file-upload handlers where the file path comes from an unvalidated request field. Migration from a library that accepted an options object as the sole argument. Conditional pipelines built as sharp(maybeInput) where maybeInput can be undefined.

Related errors

• Recursive join is unsupported
• Expected at least two images to join
• Unsupported input '${input}' of type ${typeof input}${is.def
• Expected width, height and channels for raw pixel input
• Expected raw.height ${inputOptions.raw.height} to be a multi

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