Skip to main content

Errors Documentation

Library containing all error definitions used across the TokenOps Disperse Protocol. These custom errors provide specific information about transaction failures and help with debugging.

Error Definitions​

TransferFailed​

error TransferFailed();

Description: Thrown when an ETH or token transfer operation fails.

Common Causes:

  • Recipient contract doesn't accept ETH (missing payable receive/fallback function)
  • Insufficient gas for transfer execution
  • Target contract reverted during transfer
  • Network congestion causing transaction failure

Used In: All disperse contracts during distribution operations

InvalidAddress​

error InvalidAddress();

Description: Thrown when a zero address (0x0) is provided where a valid address is required.

Common Causes:

  • Zero address provided for fee collector
  • Zero address in recipient list
  • Zero address for token contract
  • Zero address for campaign creator in custom fees

Used In: Factory deployment, fee management, distribution functions

InsufficientAmount​

error InsufficientAmount();

Description: Thrown when the provided amount is insufficient for the requested operation.

Common Causes:

  • ETH amount less than total distribution + fees
  • Token approval amount less than required
  • Insufficient balance for withdrawal
  • Payment doesn't cover minimum requirements

Used In: Distribution functions, fee calculations

InsufficientFee​

error InsufficientFee();

Description: Thrown when the fee payment is below the required amount.

Common Causes:

  • Gas fee payment doesn't match exact required amount
  • Partial fee payment provided
  • Fee calculation error in caller
  • Outdated fee amount used

Used In: Gas-based fee disperse contracts

InvalidArrayLength​

error InvalidArrayLength();

Description: Thrown when an empty array is provided where at least one element is required.

Common Causes:

  • Empty recipients array
  • Empty values array
  • Zero-length input parameters
  • Malformed batch data

Used In: All distribution functions requiring recipient/value arrays

ArrayLengthMismatch​

error ArrayLengthMismatch();

Description: Thrown when related arrays have different lengths.

Common Causes:

  • Recipients and values arrays have different sizes
  • Mismatched input data preparation
  • Partial array population
  • Data corruption during preparation

Used In: All distribution functions with multiple array parameters

ZeroBalance​

error ZeroBalance();

Description: Thrown when attempting to withdraw from an account with no available balance.

Common Causes:

  • No fees accumulated for withdrawal
  • No tokens available for recovery
  • Contract balance already withdrawn
  • Fee collector attempting withdrawal with zero fees

Used In: Fee withdrawal functions, ERC20 recovery functions

AmountTooHigh​

error AmountTooHigh();

Description: Thrown when the requested amount exceeds the available balance.

Common Causes:

  • Withdrawal amount exceeds accumulated fees
  • Transfer amount exceeds token balance
  • Requesting more than maximum allowed
  • Calculation overflow or error

Used In: Fee withdrawal functions, balance checks

OnlyFeeCollector​

error OnlyFeeCollector();

Description: Thrown when a non-fee collector address attempts to execute fee collector-only functions.

Common Causes:

  • Wrong account trying to withdraw fees
  • Fee collector role not properly transferred
  • Incorrect sender address
  • Access control violation

Used In: Fee withdrawal functions, fee collector role management

FeeTooHigh​

error FeeTooHigh();

Description: Thrown when a fee percentage exceeds the maximum allowed (100% or 10000 basis points).

Common Causes:

  • Token fee set above 10000 basis points
  • Invalid fee configuration
  • Calculation error resulting in excessive fee
  • Malicious fee setting attempt

Used In: Factory configuration, custom fee settings

CustomFeeNotSet​

error CustomFeeNotSet();

Description: Thrown when attempting to access or modify custom fees that haven't been configured.

Common Causes:

  • Trying to disable non-existent custom fee
  • Querying custom fees for unconfigured user
  • Attempting to modify uninitialized custom fee
  • Race condition in fee management

Used In: Factory custom fee management functions

Error Handling Best Practices​

1. Catch Specific Errors​

try disperseContract.disperseEther(recipients, values) {
    // Success handling
} catch Error(string memory reason) {
    // Handle known errors with reason
} catch (bytes memory lowLevelData) {
    // Handle custom errors
}

2. Validate Before Calling​

// Validate arrays
require(recipients.length > 0, "No recipients");
require(recipients.length == values.length, "Array mismatch");

// Validate addresses
require(feeCollector != address(0), "Invalid fee collector");

// Validate amounts
require(totalFee <= msg.value, "Insufficient fee payment");

3. Error Recovery​

// Implement fallback mechanisms
if (primaryMethod()) {
    return;
}
// Try alternative approach
fallbackMethod();

Troubleshooting Guide​

Common Error Scenarios​

Distribution Failures​

  • TransferFailed + InvalidAddress: Check recipient addresses are valid and can receive transfers
  • InsufficientAmount + InsufficientFee: Verify total payment covers distribution + fees
  • ArrayLengthMismatch: Ensure recipients and values arrays have same length

Fee Management Issues​

  • OnlyFeeCollector: Use correct fee collector address
  • ZeroBalance: Check if fees have been accumulated before withdrawal
  • FeeTooHigh: Ensure token fees don't exceed 10000 basis points

Configuration Problems​

  • CustomFeeNotSet: Set custom fees before trying to access them
  • InvalidAddress: Avoid zero addresses in all configurations
  • AmountTooHigh: Verify amounts don't exceed available balances