Debugging

Learn how to debug and diagnose issues with ao-forge and AO processes.

Overview

Debugging ao-forge applications involves understanding both the frontend development environment and the AO process execution. This guide covers various debugging techniques and tools.

Frontend Debugging

Development Server Debugging

Enable Debug Mode

# Start development server with debug mode
ao-forge dev --debug

# Enable verbose logging
ao-forge dev --verbose

Debug Configuration

# ao.config.yml
debug: true
verbose: true
ports:
  dev: 3000
  ao: 8080
  monitoring: 9090

Browser Developer Tools

Chrome DevTools

  1. Open DevTools - Press F12 or right-click → Inspect
  2. Console Tab - View JavaScript errors and logs
  3. Network Tab - Monitor API calls and responses
  4. Sources Tab - Set breakpoints and debug code
  5. Application Tab - Inspect local storage and cookies

React DevTools

# Install React DevTools extension
# Chrome: https://chrome.google.com/webstore/detail/react-developer-tools
# Firefox: https://addons.mozilla.org/en-US/firefox/addon/react-devtools/

Vue DevTools

# Install Vue DevTools extension
# Chrome: https://chrome.google.com/webstore/detail/vuejs-devtools
# Firefox: https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools/

Source Maps

Enable Source Maps

# Build with source maps
ao-forge build --source-maps

# Development with source maps
ao-forge dev --source-maps

Source Map Configuration

# ao.config.yml
build:
  sourceMaps: true
  optimization: false

AO Process Debugging

Process Monitoring

Enable Process Monitoring

# Start with monitoring
ao-forge dev:ao --monitor

# Monitor specific process
ao-forge process monitor my-process

Process Logs

# View process logs
ao-forge process logs my-process

# View recent logs
ao-forge process logs my-process --tail 50

# Follow logs in real-time
ao-forge process logs my-process --follow

AOS CLI Debugging

Install AOS CLI

# Install AOS CLI
npm i -g https://get_ao.g8way.io

# Check installation
aos --version

Debug AOS Commands

# Start process with debug output
aos my-process --debug

# Verbose output
aos my-process --verbose

# Check process status
aos my-process --status

Lua Code Debugging

Debug Lua Code

-- Add debug prints
print("Debug: Variable value =", variable)

-- Use AO.debug for structured logging
AO.debug("Process started", {
    processId = msg.ProcessId,
    timestamp = msg.Timestamp
})

-- Error handling
local function safeCall(func, ...)
    local success, result = pcall(func, ...)
    if not success then
        AO.error("Function call failed", {
            error = result,
            function = tostring(func)
        })
        return nil
    end
    return result
end

Lua Debugging Tools

# Use Lua debugger
lua -e "debug.debug()" your-script.lua

# Add debug hooks
debug.sethook(function(event, line)
    print("Debug hook:", event, line)
end, "l")

Common Debugging Scenarios

Process Not Starting

Check Process Status

# List all processes
ao-forge process list

# Check specific process
ao-forge process status my-process

# View process logs
ao-forge process logs my-process

Common Issues

  1. Port already in use
    # Check port usage
lsof -i :8080

# Kill process using port
kill -9 <PID>
  2. Invalid Lua syntax
    # Validate Lua syntax
lua -c your-script.lua
  3. Missing dependencies
    # Check AOS CLI installation
aos --version

# Reinstall if needed
npm i -g https://get_ao.g8way.io

Frontend Not Connecting to AO

Check Configuration

# ao.config.yml
ports:
  dev: 3000
  ao: 8080

Check Environment Variables

# Frontend environment
NEXT_PUBLIC_AO_PROCESS_ID=your-process-id
NEXT_PUBLIC_AO_GATEWAY=https://arweave.net

# AO environment
AO_WALLET_PATH=./wallet.json
AO_GATEWAY=https://arweave.net

Network Debugging

# Check if AO process is accessible
curl http://localhost:8080/status

# Check process ID
ao-forge process list

Build Failures

Check Build Logs

# Build with verbose output
ao-forge build --verbose

# Check for specific errors
ao-forge build 2>&1 | grep -i error

Common Build Issues

  1. TypeScript errors
    # Check TypeScript compilation
npx tsc --noEmit
  2. Missing dependencies
    # Install dependencies
npm install

# Check package.json
cat package.json
  3. Configuration errors
    # Validate configuration
ao-forge config validate

Debugging Tools

Logging

Frontend Logging

// Use console logging
console.log('Debug info:', data)
console.error('Error occurred:', error)
console.warn('Warning:', warning)

// Use structured logging
const logger = {
  info: (message: string, data?: any) => {
    console.log(`[INFO] ${message}`, data)
  },
  error: (message: string, error?: any) => {
    console.error(`[ERROR] ${message}`, error)
  },
  warn: (message: string, warning?: any) => {
    console.warn(`[WARN] ${message}`, warning)
  }
}

AO Process Logging

-- Use AO logging functions
AO.info("Process started", { processId = msg.ProcessId })
AO.warn("Low balance", { balance = currentBalance })
AO.error("Transaction failed", { error = errorMessage })

-- Custom logging function
local function log(level, message, data)
    local logEntry = {
        level = level,
        message = message,
        data = data,
        timestamp = msg.Timestamp,
        processId = msg.ProcessId
    }
    AO.store("log:" .. msg.Timestamp, json.encode(logEntry))
end

Performance Debugging

Frontend Performance

// Use React DevTools Profiler
import { Profiler } from 'react'

function onRenderCallback(id, phase, actualDuration) {
  console.log('Render time:', actualDuration)
}

<Profiler id="MyComponent" onRender={onRenderCallback}>
  <MyComponent />
</Profiler>

AO Process Performance

-- Measure execution time
local startTime = msg.Timestamp
-- ... process logic ...
local endTime = msg.Timestamp
local duration = endTime - startTime

AO.info("Process execution time", { duration = duration })

Debugging Best Practices

General Practices

  1. Use descriptive log messages - Include context and relevant data
  2. Log at appropriate levels - Use info, warn, error appropriately
  3. Include timestamps - Always include timing information
  4. Use structured logging - Use JSON or structured formats
  5. Don't log sensitive data - Avoid logging passwords or private keys

Frontend Debugging

  1. Use browser DevTools - Leverage built-in debugging tools
  2. Enable source maps - For better debugging experience
  3. Use React/Vue DevTools - For framework-specific debugging
  4. Monitor network requests - Check API calls and responses
  5. Test in different browsers - Ensure cross-browser compatibility

AO Process Debugging

  1. Use process monitoring - Monitor process activity and logs
  2. Validate Lua syntax - Check for syntax errors
  3. Test with AOS CLI - Use AOS CLI for direct testing
  4. Use debug prints - Add temporary debug output
  5. Check process status - Monitor process health

Troubleshooting Checklist

Before Debugging

  • Check if the issue is reproducible
  • Gather relevant error messages and logs
  • Check system requirements and dependencies
  • Verify configuration files
  • Check network connectivity

During Debugging

  • Enable debug mode and verbose logging
  • Use appropriate debugging tools
  • Check both frontend and AO process logs
  • Test with minimal configuration
  • Isolate the problem area

After Debugging

  • Document the solution
  • Update configuration if needed
  • Test the fix thoroughly
  • Consider preventing similar issues
  • Update documentation if necessary

Getting Help

Resources

Reporting Issues

When reporting issues, include:

  • ao-forge version
  • Node.js version
  • Operating system
  • Error messages and logs
  • Steps to reproduce
  • Expected vs actual behavior
Table of Contents