lovell/sharp · error · Error

Invalid input options ${inputOptions}

Error message

Invalid input options ${inputOptions}

What it means

Thrown when inputOptions is defined (not undefined) but is not an object. Sharp's input options must be a plain object; passing a number, string, array, boolean, or null as the second argument is rejected at the end of the descriptor builder. The message interpolates the offending value for visibility.

Source

Thrown at lib/input.mjs:519

          if (is.string(inputOptions.join.halign) && is.string(this.constructor.align[inputOptions.join.halign])) {
            inputDescriptor.joinHalign = this.constructor.align[inputOptions.join.halign];
          } else {
            throw is.invalidParameterError('join.halign', 'valid alignment', inputOptions.join.halign);
          }
        }
        if (is.defined(inputOptions.join.valign)) {
          if (is.string(inputOptions.join.valign) && is.string(this.constructor.align[inputOptions.join.valign])) {
            inputDescriptor.joinValign = this.constructor.align[inputOptions.join.valign];
          } else {
            throw is.invalidParameterError('join.valign', 'valid alignment', inputOptions.join.valign);
          }
        }
      } else {
        throw new Error('Expected input to be an array of images to join');
      }
    }
  } else if (is.defined(inputOptions)) {
    throw new Error(`Invalid input options ${inputOptions}`);
  }
  return inputDescriptor;
}

/**
 * Handle incoming Buffer chunk on Writable Stream.
 * @private
 * @param {Buffer} chunk
 * @param {string} encoding - unused
 * @param {Function} callback
 */
function _write (chunk, _encoding, callback) {
  if (Array.isArray(this.options.input.buffer)) {
    if (is.buffer(chunk)) {
      if (this.options.input.buffer.length === 0) {
        this.on('finish', () => {
          this.streamInFinished = true;
        });

View on GitHub (pinned to 56676c6918)

Solutions

1. Pass options as a plain object: sharp(input, { density: 72 }).
2. Double-check argument order: input first, options object second.
3. If you have no options, omit the second argument entirely rather than passing null.

Example fix

// before
sharp(input, 72)

// after
sharp(input, { density: 72 })

function sharpWithOptions(input, options) {
  if (options !== undefined && (options === null || typeof options !== 'object' || Array.isArray(options))) {
    throw new Error(`input options must be a plain object, got ${typeof options}`);
  }
  return sharp(input, options);
}

function isPlainOptionsObject(v) {
  return v === undefined || (v !== null && typeof v === 'object' && !Array.isArray(v));
}

When it happens

Trigger: sharp(input, 72) (passing a dpi number directly), sharp(input, 'png'), sharp(input, ['raw']), sharp(input, null). Mis-counting arguments so a non-options value lands in the options slot.

Common situations: Confusing sharp's options-object API with positional APIs from other libraries. Passing a partial value intending it to be a key inside options (e.g., raw density number instead of { density }). Argument-order mistakes after refactors.

Related errors

• Unsupported input '${input}' of type ${typeof input}${is.def
• Expected noise to be an object
• Expected a valid string to create an image with text.
• Invalid input
• Recursive join is unsupported

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