{"record":{"id":"7858b85d0ea3b9d5","repo":"lovell/sharp","slug":"invalid-convolution-kernel","errorCode":null,"errorMessage":"Invalid convolution kernel","messagePattern":"Invalid convolution kernel","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/operation.mjs","lineNumber":719,"sourceCode":" *\n * @param {Object} kernel\n * @param {number} kernel.width - width of the kernel in pixels.\n * @param {number} kernel.height - height of the kernel in pixels.\n * @param {Array<number>} kernel.kernel - Array of length `width*height` containing the kernel values.\n * @param {number} [kernel.scale=sum] - the scale of the kernel in pixels.\n * @param {number} [kernel.offset=0] - the offset of the kernel in pixels.\n * @returns {Sharp}\n * @throws {Error} Invalid parameters\n */\nfunction convolve (kernel) {\n  if (!is.object(kernel) || !Array.isArray(kernel.kernel) ||\n      !is.integer(kernel.width) || !is.integer(kernel.height) ||\n      !is.inRange(kernel.width, 3, 1001) || !is.inRange(kernel.height, 3, 1001) ||\n      kernel.height * kernel.width !== kernel.kernel.length ||\n      !kernel.kernel.every(is.number)\n  ) {\n    // must pass in a kernel\n    throw new Error('Invalid convolution kernel');\n  }\n  // Default scale is sum of kernel values\n  if (!is.integer(kernel.scale)) {\n    kernel.scale = kernel.kernel.reduce((a, b) => a + b, 0);\n  }\n  // Clip scale to a minimum value of 1\n  if (kernel.scale < 1) {\n    kernel.scale = 1;\n  }\n  if (!is.integer(kernel.offset)) {\n    kernel.offset = 0;\n  }\n  this.options.convKernel = kernel;\n  return this;\n}\n\n/**\n * Any pixel value greater than or equal to the threshold value will be set to 255, otherwise it will be set to 0.","sourceCodeStart":701,"sourceCodeEnd":737,"githubUrl":"https://github.com/lovell/sharp/blob/56676c69180a32b468123e090f87bfee30539b49/lib/operation.mjs#L701-L737","documentation":"Thrown by convolve() when the supplied kernel object fails any of a compound validation: it must be an object, kernel.kernel must be an array, width and height must be integers in range 3-1001, width*height must equal kernel.kernel.length, and every kernel element must be a number. Any single failure trips the whole check and rejects the kernel. Sharp needs a well-formed matrix to perform the convolution.","triggerScenarios":"convolve({ kernel: [1,1,1,1,1,1,1,1,1] }) missing width/height. convolve({ width: 3, height: 3, kernel: [1,1,1] }) (length 3 != 9). convolve({ width: 2, height: 2, kernel: [1,1,1,1] }) (width out of range 3-1001). kernel containing a non-number like null or a string.","commonSituations":"Hand-writing a kernel and miscounting elements. Using width/height of 2 thinking 2x2 is allowed (minimum is 3). Loading a kernel from JSON where numbers became strings. Off-by-one in generated kernels.","solutions":["Provide width and height as integers between 3 and 1001 inclusive.","Ensure kernel.kernel.length === width * height and every entry is a finite number.","Start from a known-good kernel (e.g., a 3x3 box blur) and modify element values only.","If loading kernels dynamically, coerce entries with Number() and validate before passing."],"exampleFix":"// before\nsharp(img).convolve({ kernel: [1,1,1,1,1,1,1,1,1] })\n\n// after\nsharp(img).convolve({ width: 3, height: 3, kernel: [1,1,1,1,1,1,1,1,1] })","handlingStrategy":"validation","validationCode":"function validKernel(kernel) {\n  if (!kernel || !Array.isArray(kernel.kernel)) throw new Error('kernel.kernel must be an array');\n  if (!Number.isInteger(kernel.width) || !Number.isInteger(kernel.height)) throw new Error('width/height must be integers');\n  if (kernel.width < 3 || kernel.width > 1001 || kernel.height < 3 || kernel.height > 1001) throw new Error('width/height must be in [3,1001]');\n  if (kernel.width * kernel.height !== kernel.kernel.length) throw new Error('kernel length must equal width*height');\n  if (!kernel.kernel.every(n => typeof n === 'number' && Number.isFinite(n))) throw new Error('all kernel values must be finite numbers');\n  return true;\n}","typeGuard":"function isValidConvolutionKernel(k) {\n  return !!k && typeof k === 'object' && Array.isArray(k.kernel) &&\n    Number.isInteger(k.width) && Number.isInteger(k.height) &&\n    k.width >= 3 && k.width <= 1001 && k.height >= 3 && k.height <= 1001 &&\n    k.width * k.height === k.kernel.length &&\n    k.kernel.every(n => typeof n === 'number' && Number.isFinite(n));\n}","tryCatchPattern":null,"preventionTips":["Always include width and height matching sqrt of the kernel length.","Keep kernel size at least 3x3.","Coerce loaded kernel values with Number() and reject non-finite entries.","Start from a known-good kernel and edit values only."],"tags":["convolve","operation","kernel","validation"],"backgroundTag":null,"analyzedSha":"56676c69180a32b468123e090f87bfee30539b49","analyzedAt":"2026-08-13T04:44:31.201Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}