Troubleshooting

This guide helps you diagnose and resolve common issues you might encounter while developing on the Arch Network.

Common Issues

Build Errors

1. Cargo Build Failures

error: failed to run custom build command for `arch-sdk v0.1.0`

Solution:

  • Ensure you have the latest Rust toolchain installed
  • Check that you're using a compatible version of the Arch SDK
  • Try cleaning your build directory: 
    cargo clean
cargo build

2. Program Compilation Errors

error: linking with `cc` failed: exit status: 1

Solution:

  • Verify you have the required system dependencies
  • Update your Arch SDK to the latest version
  • Check your program's target architecture: 
    rustup target add wasm32-unknown-unknown

Deployment Issues

1. Program Deployment Failures

Error: Program deployment failed: Transaction simulation failed

Solution:

  • Check your account has sufficient balance
  • Verify the program binary size is within limits
  • Ensure you're connected to the correct network: 
    cli config get

2. Transaction Errors

Error: Transaction failed: Custom program error: 0x1

Solution:

  • Check program logs for detailed error information
  • Verify instruction data format
  • Ensure all required accounts are provided

Runtime Issues

1. Account Creation Failures

Error: Failed to create account: insufficient funds

Solution:

  • Verify account balance
  • Check rent-exempt minimum: 
    cli rent minimum-balance <size>
  • Ensure correct account size calculation

2. Instruction Processing Errors

Error: Program failed to complete: Program failed to process instruction

Solution:

  • Enable program logging: 
    #![allow(unused)]
fn main() {
msg!("Debug output: {:?}", data);
}
  • Check account ownership
  • Verify instruction data format

Network Issues

1. Connection Problems

Error: Unable to connect to RPC endpoint

Solution:

  • Check network status
  • Verify endpoint configuration: 
    cli config get
  • Try alternate RPC endpoints

2. Validator Issues

Error: Validator node is not responding

Solution:

  • Check validator logs
  • Verify Bitcoin Core and Titan are running
  • Ensure sufficient system resources

Development Environment

1. SDK Version Mismatch

error: package `arch-sdk v0.1.0` cannot be built

Solution:

  • Update Arch SDK: 
    cargo update -p arch-sdk
  • Check compatibility matrix
  • Clean and rebuild project

2. Tool Chain Issues

error: linker `cc` not found

Solution:

  • Install required system dependencies
  • Update Rust toolchain: 
    rustup update
  • Verify PATH configuration

Performance Issues

1. Slow Transaction Processing

Solution:

  • Check compute budget usage
  • Optimize account lookups
  • Consider batching transactions

2. High Resource Usage

Solution:

  • Monitor program size
  • Optimize data structures
  • Review account storage strategy

Debugging Tools

1. Program Logs

Enable detailed logging:

RUST_LOG=debug cli program-logs <PROGRAM_ID>

2. Transaction Inspection

Analyze transaction details:

cli transaction-info <TX_SIGNATURE>

3. Account Inspection

View account data:

cli account <ACCOUNT_ADDRESS>

Best Practices

  1. Development Workflow

    • Use local validator for testing
    • Maintain separate development/production configs
    • Regular testing with minimal test accounts

  2. Error Handling

    • Implement comprehensive error types
    • Add detailed error messages
    • Log relevant debug information

  3. Maintenance

    • Regular dependency updates
    • Security audits
    • Performance monitoring

Getting Help

If you're still experiencing issues:

  1. Check the GitHub Issues
  2. Join the Discord Community
  3. Review the API Documentation

Remember to provide relevant information when seeking help:

  • Error messages
  • Program logs
  • Environment details
  • Steps to reproduce