{"record":{"id":"4f406df1c918c4c2","repo":"FuelLabs/fuels-ts","slug":"invalid-transfer-amount","errorCode":"INVALID_TRANSFER_AMOUNT","errorMessage":"Transfer amount must be a positive number.","messagePattern":"Transfer amount must be a positive number\\.","errorType":"validation","errorClass":"FuelError","httpStatus":null,"severity":"error","filePath":"packages/account/src/account.ts","lineNumber":606,"sourceCode":"    txParams: TxParamsType = {},\n    { skipAutoConsolidation }: ShouldConsolidateCoinsParams = {}\n  ): Promise<TransactionResponse> {\n    let request = new ScriptTransactionRequest({\n      ...txParams,\n    });\n\n    const quantities: CoinQuantity[] = [];\n\n    const defaultAssetId = await this.provider.getBaseAssetId();\n\n    const transferParams = contractTransferParams.map((transferParam) => {\n      const amount = bn(transferParam.amount);\n      const contractAddress = new Address(transferParam.contractId);\n\n      const assetId = transferParam.assetId ? hexlify(transferParam.assetId) : defaultAssetId;\n\n      if (amount.lte(0)) {\n        throw new FuelError(\n          ErrorCode.INVALID_TRANSFER_AMOUNT,\n          'Transfer amount must be a positive number.'\n        );\n      }\n\n      request.addContractInputAndOutput(contractAddress);\n      quantities.push({ amount, assetId });\n\n      return {\n        amount,\n        contractId: contractAddress.toB256(),\n        assetId,\n      };\n    });\n\n    const { script, scriptData } = await assembleTransferToContractScript(transferParams);\n\n    request.script = script;","sourceCodeStart":588,"sourceCodeEnd":624,"githubUrl":"https://github.com/FuelLabs/fuels-ts/blob/b3f37c91aca4aa9d5e4c0d3967f66237190826ea/packages/account/src/account.ts#L588-L624","documentation":"Thrown by Account.batchTransferToContracts (and therefore transferToContract) when a transfer amount is not greater than zero. The library rejects non-positive amounts so the Fuel VM never receives a value-less coin transfer to a contract, which would waste gas and produce a useless transaction. It is a hard precondition on every contract-bound transfer this method assembles.","triggerScenarios":"Calling account.transferToContract(contractId, amount, assetId) or account.batchTransferToContracts(params) where amount <= 0, amount is NaN (e.g. bn('abc')), amount is a numeric string '0' or '-5', or amount is undefined/null (bn coerces to 0).","commonSituations":"Passing a variable balance that happens to be zero (e.g. transferring the entire balance of an asset you do not hold), computing amount = balance.minus(fee) without guarding against negative results, sending amount as a string with a typo, or copy-pasting a test value of 0.","solutions":["Confirm the amount is strictly greater than zero before calling transferToContract/batchTransferToContracts, e.g. if (bn(amount).gt(0)) { ... } else { /* skip or notify */ }.","If the amount is derived (balance - fee - reserved), recompute it and short-circuit the transfer path when it collapses to <= 0 instead of forwarding the bad value.","Validate user-facing input upstream and surface a form error rather than letting the SDK throw at submit time."],"exampleFix":"// before\nawait account.transferToContract(contractId, balance.minus(fee), assetId);\n\n// after\nconst amount = bn(balance).sub(fee);\nif (amount.lte(0)) throw new Error('Nothing left to transfer after fees');\nawait account.transferToContract(contractId, amount, assetId);","handlingStrategy":"validation","validationCode":"import { bn } from 'fuels';\n\nfunction assertPositiveAmount(amount: unknown): void {\n  const value = bn(amount as any);\n  if (!value.gt(0)) {\n    throw new Error(`Transfer amount must be > 0, got ${amount}`);\n  }\n}\n\n// before transferToContract / batchTransferToContracts:\nassertPositiveAmount(amount);","typeGuard":"function isPositiveAmount(amount: unknown): amount is string | number | bigint {\n  try { return bn(amount as any).gt(0); } catch { return false; }\n}","tryCatchPattern":"try {\n  await account.transferToContract(contractId, amount, assetId);\n} catch (e) {\n  if (e instanceof FuelError && e.code === ErrorCode.INVALID_TRANSFER_AMOUNT) {\n    // surface user-facing 'enter a positive amount' error\n  } else throw e;\n}","preventionTips":["Compute amounts defensively and short-circuit when they collapse to <= 0.","Validate numeric inputs at the form/API boundary before reaching the SDK.","Treat 0 / negative as a no-op rather than forwarding to the SDK."],"tags":["transfer","validation","input-validation","account"],"backgroundTag":null,"analyzedSha":"b3f37c91aca4aa9d5e4c0d3967f66237190826ea","analyzedAt":"2026-08-12T20:30:56.448Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}