lovell/sharp · error · Error

Expected valid noise or background to create a new input ima

Error message

Expected valid noise or background to create a new input image

What it means

Thrown when create is used with valid dimensions and channels but neither create.noise nor create.background is provided. A synthetic image must be filled with something — either generated noise or a solid background colour — so omitting both leaves nothing to render. The error is the final else after the noise and background branches.

Source

Thrown at lib/input.mjs:384

            } else {
              throw is.invalidParameterError('create.noise.mean', 'number between 0 and 10000', inputOptions.create.noise.mean);
            }
          }
          inputDescriptor.createNoiseSigma = 30;
          if (is.defined(inputOptions.create.noise.sigma)) {
            if (is.number(inputOptions.create.noise.sigma) && is.inRange(inputOptions.create.noise.sigma, 0, 10000)) {
              inputDescriptor.createNoiseSigma = inputOptions.create.noise.sigma;
            } else {
              throw is.invalidParameterError('create.noise.sigma', 'number between 0 and 10000', inputOptions.create.noise.sigma);
            }
          }
        } else if (is.defined(inputOptions.create.background)) {
          if (!is.inRange(inputOptions.create.channels, 3, 4)) {
            throw is.invalidParameterError('create.channels', 'number between 3 and 4', inputOptions.create.channels);
          }
          inputDescriptor.createBackground = this._getBackgroundColourOption(inputOptions.create.background);
        } else {
          throw new Error('Expected valid noise or background to create a new input image');
        }
        delete inputDescriptor.buffer;
      } else {
        throw new Error('Expected valid width, height and channels to create a new input image');
      }
    }
    // Create a new image with text
    if (is.defined(inputOptions.text)) {
      if (is.object(inputOptions.text) && is.string(inputOptions.text.text)) {
        inputDescriptor.textValue = inputOptions.text.text;
        if (is.defined(inputOptions.text.height) && is.defined(inputOptions.text.dpi)) {
          throw new Error('Expected only one of dpi or height');
        }
        if (is.defined(inputOptions.text.font)) {
          if (is.string(inputOptions.text.font)) {
            inputDescriptor.textFont = inputOptions.text.font;
          } else {
            throw is.invalidParameterError('text.font', 'string', inputOptions.text.font);

View on GitHub (pinned to 56676c6918)

Solutions

1. Add a background colour: create: { width, height, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } }.
2. Or add noise: create: { width, height, channels, noise: { type: 'gaussian', mean: 128, sigma: 30 } }.
3. Remember channels must be 3-4 for background fills (a separate check enforces this).

Example fix

// before
sharp({ create: { width: 100, height: 100, channels: 3 } })

// after
sharp({ create: { width: 100, height: 100, channels: 4, background: { r: 255, g: 255, b: 255, alpha: 1 } } })

function createFilled({ width, height, channels, background, noise }) {
  if (!noise && !background) {
    throw new Error('create requires either noise or background');
  }
  if (background && ![3,4].includes(channels)) {
    throw new Error('background fill requires channels 3 or 4');
  }
  return sharp({ create: { width, height, channels, background, noise } });
}

function hasCreateFill(create) {
  return (create.noise !== undefined) || (create.background !== undefined);
}

When it happens

Trigger: sharp({ create: { width: 100, height: 100, channels: 3 } }) with no noise and no background. Providing noise/background as undefined explicitly. Building the create object dynamically where both fields ended up unset.

Common situations: Copy-paste of a create example with the fill field deleted. Assuming a default fill exists (it does not). Intending a transparent image but forgetting background: { r: 0, g: 0, b: 0, alpha: 0 }.

Related errors

• Expected noise to be an object
• Only gaussian noise is supported at the moment
• Expected create.height ${inputOptions.create.height} to be a
• Expected valid width, height and channels to create a new in
• Invalid input

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