{"record":{"id":"e598e5c56e9e55a1","repo":"lovell/sharp","slug":"expected-only-one-of-dpi-or-height","errorCode":null,"errorMessage":"Expected only one of dpi or height","messagePattern":"Expected only one of dpi or height","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/input.mjs","lineNumber":396,"sourceCode":"        } else if (is.defined(inputOptions.create.background)) {\n          if (!is.inRange(inputOptions.create.channels, 3, 4)) {\n            throw is.invalidParameterError('create.channels', 'number between 3 and 4', inputOptions.create.channels);\n          }\n          inputDescriptor.createBackground = this._getBackgroundColourOption(inputOptions.create.background);\n        } else {\n          throw new Error('Expected valid noise or background to create a new input image');\n        }\n        delete inputDescriptor.buffer;\n      } else {\n        throw new Error('Expected valid width, height and channels to create a new input image');\n      }\n    }\n    // Create a new image with text\n    if (is.defined(inputOptions.text)) {\n      if (is.object(inputOptions.text) && is.string(inputOptions.text.text)) {\n        inputDescriptor.textValue = inputOptions.text.text;\n        if (is.defined(inputOptions.text.height) && is.defined(inputOptions.text.dpi)) {\n          throw new Error('Expected only one of dpi or height');\n        }\n        if (is.defined(inputOptions.text.font)) {\n          if (is.string(inputOptions.text.font)) {\n            inputDescriptor.textFont = inputOptions.text.font;\n          } else {\n            throw is.invalidParameterError('text.font', 'string', inputOptions.text.font);\n          }\n        }\n        if (is.defined(inputOptions.text.fontfile)) {\n          if (is.string(inputOptions.text.fontfile)) {\n            inputDescriptor.textFontfile = inputOptions.text.fontfile;\n          } else {\n            throw is.invalidParameterError('text.fontfile', 'string', inputOptions.text.fontfile);\n          }\n        }\n        if (is.defined(inputOptions.text.width)) {\n          if (is.integer(inputOptions.text.width) && is.inRange(inputOptions.text.width, 1, 1000000)) {\n            inputDescriptor.textWidth = inputOptions.text.width;","sourceCodeStart":378,"sourceCodeEnd":414,"githubUrl":"https://github.com/lovell/sharp/blob/56676c69180a32b468123e090f87bfee30539b49/lib/input.mjs#L378-L414","documentation":"Thrown when creating a text image (inputOptions.text) and both text.height and text.dpi are provided. These two control the same thing — output sizing — by different means (fixed pixel height vs dots-per-inch scaling), so specifying both is contradictory. The guard is `is.defined(text.height) && is.defined(text.dpi)`.","triggerScenarios":"sharp({ text: { text: 'hello', height: 100, dpi: 72 } }). Building a text options object by merging two configs each setting one of the fields.","commonSituations":"Combining defaults from two sources. Copying examples that each used a different sizing approach. Assuming dpi only affects quality while height affects size (they are mutually exclusive sizing modes).","solutions":["Choose one sizing mode: either text.height (pixel height) or text.dpi (resolution), not both.","When merging configs, delete the unused field: delete opts.height or delete opts.dpi.","For consistent output, prefer height for fixed-size rendering and dpi for resolution-dependent rendering."],"exampleFix":"// before\nsharp({ text: { text: 'hello', height: 100, dpi: 72 } })\n\n// after\nsharp({ text: { text: 'hello', height: 100 } })","handlingStrategy":"validation","validationCode":"function textSize(opts) {\n  const { height, dpi, ...rest } = opts;\n  if (height !== undefined && dpi !== undefined) {\n    throw new Error('text: provide only one of height or dpi, not both');\n  }\n  return sharp({ text: { ...rest, height, dpi } });\n}","typeGuard":"function textHasSingleSizeMode(text) {\n  return !(text.height !== undefined && text.dpi !== undefined);\n}","tryCatchPattern":null,"preventionTips":["Pick one sizing mode (height for fixed pixels, dpi for resolution).","When merging text configs, delete the unused field.","Treat height and dpi as mutually exclusive."],"tags":["text","input","validation","mutually-exclusive"],"backgroundTag":null,"analyzedSha":"56676c69180a32b468123e090f87bfee30539b49","analyzedAt":"2026-08-13T04:44:31.201Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}