sharp

Postconditions — what we check

• toFile · tofile-rejects-on-error

  error
  Whenfile system error, invalid image data, or processing failure
  ThrowsPromise rejection with Error (ENOENT, EACCES, ENOMEM, or processing errors)
  Required handlingCaller MUST use try-catch or .catch() to handle Promise rejections from toFile(). File system errors (missing directory, permissions), invalid image data, and memory issues will reject the Promise and crash the application if unhandled. Use pattern: try { await sharp(input).toFile('output.jpg'); } catch (error) { /* handle */ }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• toBuffer · tobuffer-rejects-on-error

  error
  Wheninvalid image data or processing failure
  ThrowsPromise rejection with Error
  Required handlingCaller MUST use try-catch or .catch() to handle Promise rejections from toBuffer(). Invalid or corrupted image data will reject the Promise and crash if unhandled. Use pattern: try { const buffer = await sharp(input).toBuffer(); } catch (error) { /* handle */ }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• metadata · metadata-rejects-on-corrupt-or-unsupported-input

  error
  WhenInput image has a corrupt header, is not a recognized image format, or the input file is missing from the filesystem. Also rejects if the image exceeds the pixel limit (default 268,402,689 pixels) when limitInputPixels is set.
  ThrowsPromise rejection with Error whose message begins with one of: "Input file is missing: <path>", "Input file has corrupt header: <libvips error>", "Input file contains unsupported image format", "Input buffer has corrupt header: <libvips error>", "Input buffer contains unsupported image format", "Input image exceeds pixel limit". All originate from libvips VError converted to a native JS Error via is.nativeError() in lib/input.js.
  Required handlingCaller MUST wrap await sharp(input).metadata() in try-catch. Used in upload validation pipelines to check if a file is a genuine image — if the call throws, it must be caught or it silently crashes the upload handler and returns a 500 to the client. Correct pattern: try { const meta = await sharp(inputBuffer).metadata(); // Use meta.width, meta.height, meta.format } catch (error) { // Input is corrupt, unsupported, or file is missing throw new Error(`Invalid image: ${error.message}`); } Note: metadata() reads only the header — a successful metadata() call does NOT guarantee the full image is valid. Corrupt pixel data surfaces only when toBuffer() or toFile() decodes the full image.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3][4][5]
• stats · stats-rejects-on-corrupt-or-unsupported-input

  error
  WhenInput image cannot be fully decoded: corrupt file, unsupported format, missing input file, or pixel limit exceeded. Unlike metadata(), stats() decodes all pixel data so corrupt pixel data (not just header corruption) will also cause rejection.
  ThrowsPromise rejection with Error whose message originates from libvips VError: "Input file is missing: <path>", "Input file has corrupt header: <libvips error>", "Input file contains unsupported image format", "Input buffer has corrupt header: <libvips error>", "Input buffer contains unsupported image format", or any libvips processing error from full pixel decode.
  Required handlingCaller MUST wrap await sharp(input).stats() in try-catch. stats() is often used for image quality analysis (is it blurry? colorful?). When called without error handling on unvalidated user uploads, a corrupt image will crash the analysis pipeline and leave jobs stuck. Correct pattern: try { const { entropy, sharpness, dominant } = await sharp(inputBuffer).stats(); // Use entropy to detect blank images, sharpness for blur detection } catch (error) { console.error('Image stats failed:', error.message); throw error; } Critical gotcha: statistics are derived from the ORIGINAL input image. If you want stats on a resized/cropped region, you MUST first do: const part = await sharp(input).extract(region).toBuffer(); const s = await sharp(part).stats(); // Stats on the cropped region Calling .extract(region).stats() without intermediate toBuffer() reads stats from the original unmodified image — a silent data correctness bug.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][7][4]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]sharp.pixelplumbing.com/api-outputhttps://sharp.pixelplumbing.com/api-output#tofile
2. [2]sharp.pixelplumbing.com/api-outputhttps://sharp.pixelplumbing.com/api-output#tobuffer
3. [3]sharp.pixelplumbing.com/api-inputhttps://sharp.pixelplumbing.com/api-input#metadata
4. [4]github.com/lovell/sharphttps://github.com/lovell/sharp/blob/main/src/common.cc
5. [5]github.com/lovell/sharphttps://github.com/lovell/sharp/blob/main/src/metadata.cc
6. [6]sharp.pixelplumbing.com/api-inputhttps://sharp.pixelplumbing.com/api-input#stats
7. [7]github.com/lovell/sharphttps://github.com/lovell/sharp/blob/main/src/stats.cc