{"record":{"id":"b1000a82e9e25c38","repo":"FuelLabs/fuels-ts","slug":"converting-failed","errorCode":"CONVERTING_FAILED","errorMessage":"Cannot convert negative value to hex.","messagePattern":"Cannot convert negative value to hex\\.","errorType":"exception","errorClass":"FuelError","httpStatus":null,"severity":"error","filePath":"packages/math/src/bn.ts","lineNumber":87,"sourceCode":"\n  // ANCHOR: HELPERS\n  // make sure we always include `0x` in hex strings\n  override toString(base?: number | 'hex', length?: number) {\n    const output = super.toString(base, length);\n\n    if (base === 16 || base === 'hex') {\n      return `0x${output}`;\n    }\n\n    return output;\n  }\n\n  toHex(bytesPadding?: number): string {\n    const bytes = bytesPadding || 0;\n    const bytesLength = bytes * 2;\n\n    if (this.isNeg()) {\n      throw new FuelError(ErrorCode.CONVERTING_FAILED, 'Cannot convert negative value to hex.');\n    }\n    if (bytesPadding && this.byteLength() > bytesPadding) {\n      throw new FuelError(\n        ErrorCode.CONVERTING_FAILED,\n        `Provided value ${this} is too large. It should fit within ${bytesPadding} bytes.`\n      );\n    }\n\n    return this.toString(16, bytesLength);\n  }\n\n  toBytes(bytesPadding?: number): Uint8Array {\n    if (this.isNeg()) {\n      throw new FuelError(ErrorCode.CONVERTING_FAILED, 'Cannot convert negative value to bytes.');\n    }\n\n    return Uint8Array.from(this.toArray(undefined, bytesPadding));\n  }","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/FuelLabs/fuels-ts/blob/b3f37c91aca4aa9d5e4c0d3967f66237190826ea/packages/math/src/bn.ts#L69-L105","documentation":"Thrown by BN.toHex() when the value is negative. Hex output in this SDK is intended for unsigned, fixed-size field encoding (e.g. U256), and a negative sign has no representation in that scheme, so the conversion is rejected.","triggerScenarios":"Calling `.toHex()` on a BN produced by subtraction that went below zero, or constructed from a negative literal like `bn(-5)`.","commonSituations":"Balance arithmetic underflow (subtracting more than available), signed computation leaking into an unsigned encoding path, unexpected negative result from `fromTwos`/two's-complement misuse.","solutions":["Check `isNeg()` before toHex and decide how to handle it (clamp to 0, absolute value, or surface a domain error).","Guard the upstream arithmetic so values fed into encoding are non-negative.","Use `.abs()` if you genuinely want the magnitude."],"exampleFix":"// before\nconst v = a.sub(b); // may be negative\nconst hex = v.toHex();\n// after\nif (v.isNeg()) {\n  throw new Error('result must be non-negative');\n}\nconst hex = v.toHex();","handlingStrategy":"validation","validationCode":"function safeToHex(v: import('@fuel-ts/math').BN, pad?: number): string {\n  if (v.isNeg()) throw new Error('cannot encode negative value to hex');\n  return v.toHex(pad);\n}","typeGuard":"const isNonNegative = (v: import('@fuel-ts/math').BN): boolean => !v.isNeg();","tryCatchPattern":null,"preventionTips":["Check isNeg() before any toHex/toBytes call on computed values.","Clamp balance arithmetic to zero on underflow where appropriate.","Keep encoding paths unsigned by construction."],"tags":["math","bn","hex","conversion","signedness"],"backgroundTag":null,"analyzedSha":"b3f37c91aca4aa9d5e4c0d3967f66237190826ea","analyzedAt":"2026-08-12T20:30:56.448Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}