Troubleshooting Guide

This guide provides comprehensive troubleshooting steps for common issues encountered when working with the Cart.fun protocol. Use it to diagnose and resolve problems during development, testing, and production deployments.

When encountering an error, always capture the full error message, code, and program logs. This information is crucial for effective troubleshooting.

General Approach

When encountering issues with the Cart.fun protocol, follow these general steps:

•

Identify the Error

Capture the exact error message and code.

•

Check Logs

Review program logs for detailed error information.

•

Verify Account Status

Ensure all relevant accounts are active.

•

Check Authority

Verify the correct authority is being used.

•

Review Parameters

Validate all transaction parameters.
•

Consult Documentation

Check relevant documentation for requirements.

•

Test with Smaller Steps

Break complex operations into smaller testable steps.

•

Simulate Transactions

Use transaction simulation to diagnose issues before submission.

Error Collection Methodology

For effective troubleshooting, collect the following information:

try {
  // Attempted operation
  await sdk.performOperation(...);
} catch (error) {
  console.error({
    message: error.message,
    code: error.code,
    logs: error.logs,
    instruction: "performOperation",
    params: { /* parameters used */ },
    timestamp: new Date().toISOString()
  });
}

Account & PDA Issues

Account Not Found

  • Name
    Symptoms
    Description
    • "Account not found" or "Account does not exist" - Failed account lookup operations
  • Name
    Possible Causes
    Description
    • Account hasn't been initialized - Incorrect account address calculation - Account was closed or deactivated

Solutions

  1. Verify account existence using connection.getAccountInfo()
  2. Check PDA derivation seeds for correctness
  3. Review account initialization code
  4. Check for typos in public keys or seeds

Example Diagnosis:

// Verify account exists
const accountInfo = await connection.getAccountInfo(accountAddress)
if (!accountInfo) {
  console.error('Account does not exist')

  // Check if PDA derivation is correct
  const [expectedAddress] = await PublicKey.findProgramAddress(
    [Buffer.from('marketplace'), marketplaceOwner.toBuffer()],
    programId,
  )

  console.log('Expected address:', expectedAddress.toString())
  console.log('Attempted address:', accountAddress.toString())
}

Incorrect Account Owner

  • Name
    Symptoms
    Description
    • "Account does not have correct program id" - Failed account data deserialization
  • Name
    Possible Causes
    Description
    • Attempting to use account from another program - Using outdated program ID
    • Account was created by a different program version

Solutions

  1. Verify the account's owner matches the expected program ID
  2. Ensure you're using the correct program ID for the network (Mainnet/Devnet)
  3. Check if the account needs to be initialized by the Cart.fun program

Example Diagnosis:

const accountInfo = await connection.getAccountInfo(accountAddress)
if (accountInfo) {
  console.log('Account owner:', accountInfo.owner.toString())
  console.log('Expected program ID:', programId.toString())

  if (!accountInfo.owner.equals(programId)) {
    console.error('Account has incorrect owner')
    // Account is owned by another program
  }
}

PDA Derivation Issues

  • Name
    Symptoms
    Description
    • Cannot find account at derived address - "Invalid seeds" or "Invalid PDA" errors
  • Name
    Possible Causes
    Description
    • Incorrect seed format or encoding - Wrong seed order - Missing or extra seeds - Using different programId for derivation than creation

Solutions

  1. Double-check all seed values
  2. Ensure consistent encoding (UTF-8 for strings)
  3. Verify seed order matches the order used during creation
  4. Make sure the correct program ID is used

Example Diagnosis:

// Examining PDA derivation
const seeds = [
  Buffer.from('vendor'),
  marketplaceAddress.toBuffer(),
  Buffer.from(vendorId),
]

// Check each seed for expected values
seeds.forEach((seed, index) => {
  console.log(`Seed ${index}:`, seed.toString('hex'))
})

const [derivedAddress, bump] = await PublicKey.findProgramAddress(
  seeds,
  programId,
)
console.log('Derived address:', derivedAddress.toString())
console.log('Bump seed:', bump)

Transaction Failures

Insufficient Funds

  • Name
    Symptoms
    Description
    • "Insufficient funds for fee" error - Transaction rejected due to balance issues
  • Name
    Possible Causes
    Description
    • Payer account has insufficient SOL - Attempting to transfer more tokens than available - Fee calculation error

Solutions

  1. Check account balance before transaction
  2. Ensure fee calculation is correct
  3. Add funds to the payer account
  4. Reduce transaction complexity (fewer instructions) to reduce fees

Example Diagnosis:

// Check SOL balance
const balance = await connection.getBalance(payerAddress)
console.log('Account balance:', balance / LAMPORTS_PER_SOL, 'SOL')

// Check token balance
const tokenAccountInfo = await getAccount(connection, tokenAccountAddress)
console.log('Token balance:', tokenAccountInfo.amount.toString())

// Estimate transaction fee
const { feeCalculator } = await connection.getRecentBlockhash()
const estimatedFee =
  feeCalculator.lamportsPerSignature * transaction.signatures.length
console.log('Estimated fee:', estimatedFee / LAMPORTS_PER_SOL, 'SOL')

Permission Denied

  • Name
    Symptoms
    Description
    • "Access denied" or "Unauthorized" errors - Failure to modify or access certain accounts
  • Name
    Possible Causes
    Description
    • Using the wrong authority account - Authority not included as a signer - Permission level mismatch

Solutions

  1. Verify the authority is the correct one
  2. Ensure the authority is added as a signer
  3. Check permission hierarchies (Protocol → Platform → Marketplace → Vendor)
  4. Review access control rules for the specific operation

Example Diagnosis:

// Check if authority matches expected
console.log('Authority used:', authority.publicKey.toString())
console.log('Expected authority:', expectedAuthority.toString())

// Verify authority is a signer
const isAuthoritySigner = transaction.signatures.some((sig) =>
  sig.publicKey.equals(authority.publicKey),
)
console.log('Is authority a signer:', isAuthoritySigner)

SDK & Client Issues

SDK Version Mismatch

  • Name
    Symptoms
    Description
    • Unexpected API errors - Missing methods or parameters - Breaking behavior changes
  • Name
    Possible Causes
    Description
    • Using outdated SDK version - Incompatible SDK and program versions - Breaking changes in SDK update

Solutions

  1. Update to the latest SDK version
  2. Check SDK version compatibility with program version
  3. Read SDK release notes for breaking changes
  4. Test with specific known good versions

Example Diagnosis:

// Check SDK version
console.log(
  'Cart Protocol SDK version:',
  require('@cartdotfun/sdk/package.json').version,
)

// Check compatible program versions
console.log('Compatible program versions:', SDK_COMPATIBLE_VERSIONS)

Connection Issues

  • Name
    Symptoms
    Description
    • "Connection error" or "Network error" - Timeouts during operations - Intermittent failures
  • Name
    Possible Causes
    Description
    • RPC node overloaded or down - Rate limiting - Network connectivity issues
    • Incorrect RPC URL

Solutions

  1. Try alternate RPC endpoints
  2. Implement retry logic with exponential backoff
  3. Check RPC endpoint status
  4. Verify network configuration (Mainnet/Devnet/Testnet)

Example Diagnosis:

// Try multiple RPC endpoints
const endpoints = [
  'https://api.mainnet-beta.solana.com',
  'https://solana-api.projectserum.com',
  'https://rpc.ankr.com/solana',
]

for (const endpoint of endpoints) {
  try {
    const connection = new Connection(endpoint)
    await connection.getLatestBlockhash()
    console.log(`Connection successful to ${endpoint}`)
    break
  } catch (error) {
    console.error(`Connection failed to ${endpoint}:`, error.message)
  }
}

Advanced Debugging

Transaction Simulation

Simulate transactions before submitting them to diagnose issues without paying fees:

// Simulate transaction to check for errors
const { value } = await connection.simulateTransaction(transaction)

if (value.err) {
  console.error('Simulation error:', value.err)
  // Parse logs for detailed error information
  const logs = value.logs || []
  console.log('Simulation logs:', logs)

  // Look for specific error patterns
  const programErrorLog = logs.find((log) =>
    log.includes('Program log: Error:'),
  )
  if (programErrorLog) {
    console.error('Program error:', programErrorLog)
  }
}

Log Analysis

Learn to interpret program logs for detailed error information:

Program log: Instruction: CreateMarketplace
Program log: Error: AccessDenied
Program log: Error in account #2
Program Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS consumed 5431 of 200000 compute units
Program failed to complete: custom program error: 0x1

In this example:

  • The failed instruction was CreateMarketplace
  • The error type was AccessDenied
  • The issue was in account #2
  • The program ID is Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS
  • Error code 0x1 corresponds to a specific Cart.fun error

Debug Mode

Enable debug mode in the SDK for more verbose output:

// Enable debug mode
const cartProtocol = new CartProtocol({
  connection,
  wallet,
  network: NetworkType.Devnet,
  options: {
    debug: true,
    logLevel: 'verbose',
  },
})

Getting Help

If you've tried the troubleshooting steps and still can't resolve your issue:

  1. Check Known Issues: Review the GitHub issues for similar problems
  2. Community Forums: Ask in the Cart.fun Discord community
  3. SDK Documentation: Review the TypeScript SDK documentation
  4. Error Reference: Check the Common Error Codes documentation
  5. Submit a Bug Report: If you've found a new issue, submit a bug report with detailed reproduction steps

Resources

Error Reference

Detailed explanations of all error codes

SDK Guides

Guides for using the TypeScript SDK

GitHub Repository

Browse source code and report issues

Discord Community

Get help from the Cart.fun community

Was this page helpful?