Exit Codes

AWF uses standardized exit codes to indicate the type of error that occurred.

Exit Code Reference#

Error Categories#

Exit Code 0: Success#

The workflow executed and reached a terminal state with status: success.

awf run my-workflow
echo $?  # 0

Exit Code 1: User Error#

The user provided invalid input or the requested resource doesn’t exist.

Common causes:

• Invalid command-line flag
• Missing required input parameter
• Workflow file not found
• Invalid input value (validation failed)

Examples:

# Missing required input
awf run deploy
# Error: missing required input: env

# Workflow not found
awf run nonexistent
# Error: workflow 'nonexistent' not found

# Invalid input value
awf run deploy --input env=invalid
# Error: input validation failed: enum values are [dev, staging, prod]

Exit Code 2: Workflow Error#

The workflow definition contains errors detected at load or validation time.

Common causes:

• Invalid state reference (state doesn’t exist)
• Cycle detected in state transitions
• Unreachable states
• Missing terminal state
• Invalid template reference
• Forward reference (step A references step B before B executes)

Examples:

# Invalid state reference
awf validate my-workflow
# Error: state 'missing_state' referenced but not defined

# Cycle detected
awf validate my-workflow
# Error: cycle detected: step1 -> step2 -> step1

# Missing terminal
awf validate my-workflow
# Error: no terminal state found

Exit Code 3: Execution Error#

A command failed during execution.

Common causes:

• Command returned non-zero exit code
• Command timed out
• Step failed after all retry attempts
• Parallel step failed (with all_succeed strategy)

Examples:

# Command failed
awf run deploy
# Error: step 'build' failed with exit code 1

# Timeout
awf run long-task
# Error: step 'process' timed out after 30s

# Retry exhausted
awf run flaky-api
# Error: step 'api_call' failed after 5 attempts

Exit Code 4: System Error#

A system-level error prevented execution.

Common causes:

• Permission denied (file or directory)
• Disk full
• Network error
• Database error (history storage)
• Unable to create temp files

Examples:

# Permission denied
awf run my-workflow
# Error: permission denied: /etc/config

# Storage error
awf history
# Error: failed to open history database

Using Exit Codes in Scripts#

#!/bin/bash

awf run deploy --input env=prod
exit_code=$?

case $exit_code in
  0)
    echo "Deployment successful"
    ;;
  1)
    echo "Invalid input - check your parameters"
    ;;
  2)
    echo "Workflow error - validate your workflow"
    ;;
  3)
    echo "Execution failed - check command output"
    ;;
  4)
    echo "System error - check permissions and disk space"
    ;;
  *)
    echo "Unknown error: $exit_code"
    ;;
esac

JSON Error Output#

Use --format json for structured error information:

awf run deploy -f json

{
  "success": false,
  "error": {
    "code": 3,
    "error_code": "EXECUTION.COMMAND.FAILED",
    "type": "execution_error",
    "message": "step 'build' failed with exit code 1",
    "step": "build",
    "details": {
      "exit_code": 1,
      "output": "make: *** No rule to make target 'build'."
    },
    "timestamp": "2025-01-15T10:30:45Z"
  }
}

When a structured error code is available, the error_code field contains the hierarchical error code (e.g., EXECUTION.COMMAND.FAILED). See Error Codes for the full taxonomy.

See Also#

• Error Codes - Structured error taxonomy and detailed error codes
• Commands - CLI command reference
• Workflow Syntax - Workflow definition