Error Messages

Understanding error codes and messages in ao-forge.

Overview

ao-forge provides detailed error messages to help diagnose and resolve issues. This document explains common error codes and their solutions.

Error Code Reference

Project Errors

`PROJECT_NOT_FOUND`

Message: "Project directory not found" Cause: The specified project directory doesn't exist Solution:

# Check if directory exists
ls -la ./my-project

# Create project if needed
ao-forge init my-project

`INVALID_PROJECT_STRUCTURE`

Message: "Invalid project structure detected" Cause: Project files are missing or corrupted Solution:

# Validate project structure
ao-forge config validate

# Recreate project if needed
ao-forge init my-project --force

Configuration Errors

`INVALID_CONFIG`

Message: "Configuration file is invalid" Cause: ao.config.yml has syntax or validation errors Solution:

# Validate configuration
ao-forge config validate

# Check YAML syntax
cat ao.config.yml

# Fix configuration issues
ao-forge config fix

`MISSING_REQUIRED_FIELD`

Message: "Required field '{field}' is missing" Cause: Required configuration field is not specified Solution:

# Add missing field to ao.config.yml
name: 'my-ao-app'
framework: 'nextjs'  # Add this if missing
packageManager: 'pnpm'  # Add this if missing

`INVALID_FRAMEWORK`

Message: "Invalid framework '{framework}'" Cause: Unsupported framework specified Solution:

# Use supported framework
framework: 'nextjs'  # or 'nuxtjs'

`INVALID_PACKAGE_MANAGER`

Message: "Invalid package manager '{manager}'" Cause: Unsupported package manager specified Solution:

# Use supported package manager
packageManager: 'pnpm'  # or 'npm', 'yarn'

Process Errors

`PROCESS_FAILED`

Message: "Process '{name}' failed to start" Cause: AO process failed to initialize or start Solution:

# Check process logs
ao-forge process logs my-process

# Check AOS CLI installation
aos --version

# Restart process
ao-forge process restart my-process

`PROCESS_NOT_FOUND`

Message: "Process '{name}' not found" Cause: Specified process doesn't exist Solution:

# List available processes
ao-forge process list

# Check process configuration
ao-forge config get processes

`PROCESS_ALREADY_RUNNING`

Message: "Process '{name}' is already running" Cause: Process is already started Solution:

# Stop existing process
ao-forge process stop my-process

# Or restart process
ao-forge process restart my-process

`AOS_NOT_INSTALLED`

Message: "AOS CLI is not installed" Cause: AOS CLI tool is not available Solution:

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

# Verify installation
aos --version

Build Errors

`BUILD_FAILED`

Message: "Build process failed" Cause: Build compilation or optimization failed Solution:

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

# Check for TypeScript errors
npx tsc --noEmit

# Check for missing dependencies
npm install

`INVALID_BUILD_CONFIG`

Message: "Invalid build configuration" Cause: Build settings are incorrect Solution:

# Fix build configuration
build:
  output: './dist'
  optimize: true
  sourceMaps: false
  minify: true

`BUILD_OUTPUT_NOT_FOUND`

Message: "Build output directory not found" Cause: Build output directory doesn't exist Solution:

# Create output directory
mkdir -p ./dist

# Run build again
ao-forge build

Deployment Errors

`DEPLOYMENT_FAILED`

Message: "Deployment to '{platform}' failed" Cause: Deployment process encountered an error Solution:

# Check deployment configuration
ao-forge config get deploy

# Verify platform credentials
# Check network connectivity
# Review deployment logs

`INVALID_DEPLOYMENT_CONFIG`

Message: "Invalid deployment configuration" Cause: Deployment settings are incorrect Solution:

# Fix deployment configuration
deploy:
  platform: 'vercel'
  environment: 'production'
  domain: 'my-app.vercel.app'

`PLATFORM_NOT_SUPPORTED`

Message: "Platform '{platform}' is not supported" Cause: Unsupported deployment platform Solution:

# Use supported platform
deploy:
  platform: 'vercel'  # or 'netlify', 'github', 'docker'

Network Errors

`NETWORK_ERROR`

Message: "Network connection failed" Cause: Network connectivity issues Solution:

# Check internet connection
ping google.com

# Check firewall settings
# Verify proxy configuration
# Try different network

`CONNECTION_TIMEOUT`

Message: "Connection timeout" Cause: Network request timed out Solution:

# Increase timeout settings
# Check network stability
# Verify server availability

Permission Errors

`INSUFFICIENT_PERMISSIONS`

Message: "Insufficient permissions to perform operation" Cause: User doesn't have required permissions Solution:

# Check file permissions
ls -la

# Fix permissions if needed
chmod 755 ./my-project

# Run with appropriate permissions
sudo ao-forge init my-project

`FILE_ACCESS_DENIED`

Message: "Access denied to file '{file}'" Cause: File is locked or inaccessible Solution:

# Check if file is in use
lsof ./file.lua

# Kill process using file
kill -9 <PID>

# Check file permissions
ls -la ./file.lua

Port Errors

`PORT_ALREADY_IN_USE`

Message: "Port {port} is already in use" Cause: Another process is using the specified port Solution:

# Check what's using the port
lsof -i :3000

# Kill process using port
kill -9 <PID>

# Use different port
ao-forge dev --port 3001

`INVALID_PORT`

Message: "Invalid port number '{port}'" Cause: Port number is out of valid range Solution:

# Use valid port number (1-65535)
ao-forge dev --port 3000

Validation Errors

`VALIDATION_ERROR`

Message: "Validation failed: {details}" Cause: Input validation failed Solution:

# Check input format
# Verify required fields
# Use correct data types

`SCHEMA_VALIDATION_FAILED`

Message: "Schema validation failed" Cause: Data doesn't match expected schema Solution:

# Validate against schema
ao-forge config validate

# Check data format
# Verify field types

Error Handling

Frontend Error Handling

try {
  const result = await aoForgeCommand()
} catch (error) {
  if (error.code === 'PROCESS_FAILED') {
    console.error('Process failed:', error.message)
    // Handle process failure
  } else if (error.code === 'NETWORK_ERROR') {
    console.error('Network error:', error.message)
    // Handle network error
  } else {
    console.error('Unknown error:', error.message)
    // Handle unknown error
  }
}

AO Process Error Handling

-- Handle errors in Lua code
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

-- Validate inputs
local function validateInput(msg)
    if not msg.Input then
        return { error = "Missing input" }
    end
    
    if type(msg.Input) ~= "string" then
        return { error = "Invalid input type" }
    end
    
    return { success = true }
end

Debugging Error Messages

Enable Verbose Logging

# Enable verbose output
ao-forge dev --verbose

# Enable debug mode
ao-forge dev --debug

Check Logs

# View process logs
ao-forge process logs

# View build logs
ao-forge build --verbose

# View deployment logs
ao-forge deploy --verbose

Error Context

When encountering errors, gather:

Error message and code
Command that caused the error
Configuration files
System information
Log files
Steps to reproduce

Best Practices

Error Prevention

Validate inputs - Check all inputs before processing
Handle errors gracefully - Provide meaningful error messages
Use proper error codes - Use consistent error codes
Log errors appropriately - Log errors with context
Test error scenarios - Test error handling paths

Error Recovery

Provide recovery options - Suggest solutions in error messages
Enable retry mechanisms - Allow retrying failed operations
Graceful degradation - Continue operation when possible
User-friendly messages - Make errors understandable
Documentation - Document common errors and solutions

Getting Help

Resources

Common Issues - Frequently encountered problems
Debugging Guide - Debugging techniques
GitHub Issues - Report bugs
Discord Community - Community support

Reporting Errors

When reporting errors, include:

Error code and message
Command that caused the error
Configuration files
System information
Steps to reproduce
Expected vs actual behavior

TroubleshootingDebugging

ContributingSetup