Introduction link

The IPM CLI returns specific exit codes to indicate the success or failure of operations. These codes help with automation, scripting, and debugging by providing detailed information about what went wrong during command execution.

Exit Code Categories link

Exit codes are organized into logical groups based on the type of operation or error:

• 0: Success
• 100-199: Informational codes
• Negative codes: Error conditions (displayed as positive values on Linux/macOS)

Success and Information Codes link

Success link

• 0 - Ok: Operation completed successfully

Informational link

• 100 - NoVersionFoundForPackage: No “latest” version available for package
• 101 - SpecifiedVersionNotFoundForPackage: Specified version not found for package
• 200 - SearchNoResults: Search operation returned no results

Error Codes link

Validation - Formatting (-100 to -109) link

Validation - Generic/Workspace (-110 to -149) link

Actions - Build/Pack (-200 to -209) link

Actions - Publish (-210 to -219) link

Actions - Extract/Export (-230 to -239) link

Actions - Add (-240 to -249) link

Sync (-250 to -259) link

Search (-260 to -269) link

Package Download (-270 to -279) link

CLI Configuration (-300 to -309) link

Authentication (-400 to -449) link

Client Secrets/Non-Interactive (-450 to -459) link

Generic (-1 to -9) link

Using Exit Codes in Scripts link

Using Exit Codes in Scripts link

Bash/Shell Scripts (Linux/macOS) link

#!/bin/bash

### Run IPM command and capture exit code
ipm add --package mycompany/mypackage
EXIT_CODE=$?

case $EXIT_CODE in
    0)
        echo "Package added successfully"
        ;;
    136)  # PackageNotFound
        echo "Error: Package not found. Check the package name."
        exit 1
        ;;
    43)   # PublishFailedUnauthorized
        echo "Error: Not authenticated. Running login..."
        ipm login
        ;;
    42)   # PublishFailedForbidden
        echo "Error: Insufficient permissions. Contact your administrator."
        exit 1
        ;;
    *)
        echo "Unexpected error occurred (exit code: $EXIT_CODE)"
        exit 1
        ;;
esac

PowerShell Scripts (Windows) link

### Run IPM command and handle exit codes
& ipm add --package mycompany/mypackage
$exitCode = $LASTEXITCODE

switch ($exitCode) {
    0 { 
        Write-Host "Package added successfully" -ForegroundColor Green 
    }
    -120 {  # PackageNotFound
        Write-Host "Error: Package not found. Check the package name." -ForegroundColor Red
        exit 1
    }
    -213 {  # PublishFailedUnauthorized
        Write-Host "Error: Not authenticated. Running login..." -ForegroundColor Yellow
        & ipm login
    }
    -214 {  # PublishFailedForbidden
        Write-Host "Error: Insufficient permissions. Contact your administrator." -ForegroundColor Red
        exit 1
    }
    default { 
        Write-Host "Unexpected error occurred (exit code: $exitCode)" -ForegroundColor Red
        exit 1
    }
}

CI/CD Pipeline Integration link

# Azure DevOps Pipeline example
- task: Bash@3
  displayName: 'Add Package'
  inputs:
    targetType: 'inline'
    script: |
      ipm add --package mycompany/mypackage --non-interactive
      EXIT_CODE=$?
      
      # On Linux/macOS: -213 becomes 43, -405 becomes 107, -120 becomes 136
      if [ $EXIT_CODE -eq 43 ] || [ $EXIT_CODE -eq 107 ]; then
        echo "##vso[task.logissue type=error]Authentication required"
        exit 1
      elif [ $EXIT_CODE -eq 136 ]; then
        echo "##vso[task.logissue type=error]Package not found"
        exit 1
      elif [ $EXIT_CODE -ne 0 ]; then
        echo "##vso[task.logissue type=error]IPM command failed with exit code $EXIT_CODE"
        exit 1
      fi
      
      echo "Package added successfully"

Troubleshooting Common Exit Codes link

Authentication Issues (-400 series, Linux/macOS: 99-112) link

Most authentication problems can be resolved by:

1. Running ipm login for interactive authentication
2. Providing valid client secrets for non-interactive scenarios
3. Checking network connectivity to IPMHub

Package Not Found (-120/-121, Linux/macOS: 135-136) link

When packages aren’t found:

1. Verify the package name spelling
2. Check if the package exists using ipm search
3. Ensure you have access permissions for private/hybrid packages
4. For specific versions, use ipm info to see available versions

Permission Issues (-214/-271, Linux/macOS: 42/241) link

Permission errors typically require:

1. Organization membership for private packages
2. Contributor role for publishing operations
3. Valid subscription for premium features

Workspace Issues (-130/-131, Linux/macOS: 125-126) link

Workspace-related errors usually need:

1. Running ipm init to initialize workspace
2. Fixing syntax errors in ipmhub.json
3. Ensuring proper file permissions

Best Practices link

Error Handling in Automation link

1. Always check exit codes in automated scripts
2. Account for platform differences (negative codes on Windows, positive on Linux/macOS)
3. Provide meaningful error messages based on specific exit codes
4. Implement retry logic for transient errors (network issues)
5. Log exit codes for debugging and monitoring

Debugging with Exit Codes link

1. Use verbose logging (--loglevel Debug) when debugging
2. Check specific error categories to narrow down issues
3. Verify prerequisites (authentication, permissions, network) first
4. Consult documentation for error-specific solutions
5. Remember platform-specific exit code conversions when troubleshooting