errors

Error Handling Package

This package provides standardized error handling for the Buildkite CLI. It handles different types of errors consistently, provides helpful error messages and suggestions to users, and ensures a unified approach to error reporting across the application.

Features

• Categorized Errors: Different error types (validation, API, not found, etc.) with specific handling
• Contextual Error Messages: Errors include context about what operation failed
• Helpful Suggestions: Error messages include suggestions on how to fix the issue
• Command Integration: Easy integration with Kong commands
• API Error Handling: Specialized handling for API errors with status code interpretation
• Exit Codes: Appropriate exit codes for different error types

Usage

Creating Errors

import (
    bkErrors "github.com/buildkite/cli/v3/internal/errors"
)

// Create various types of errors
validationErr := bkErrors.NewValidationError(
    err, // Original error (can be nil)
    "Invalid input", // Details about the error
    "Try using a different value", // Suggestions (optional)
    "Check the documentation for valid options" // More suggestions
)

apiErr := bkErrors.NewAPIError(err, "API request failed")

notFoundErr := bkErrors.NewResourceNotFoundError(err, "Resource not found")

Adding Context to Errors

// Add suggestions to an existing error
err = bkErrors.WithSuggestions(err,
    "Try this instead",
    "Or try this other option"
)

// Add details to an existing error
err = bkErrors.WithDetails(err, "Additional context")

Checking Error Types

if bkErrors.IsNotFound(err) {
    // Handle not found error
}

if bkErrors.IsValidationError(err) {
    // Handle validation error
}

if bkErrors.IsAPIError(err) {
    // Handle API error
}

Wrapping API Errors

// Wrap HTTP errors with appropriate context
err = bkErrors.WrapAPIError(err, "fetching pipeline")

Command Integration

// Wrap a command's RunE function with standard error handling
cmd := &cobra.Command{
    RunE: bkErrors.WrapRunE(func(cmd *cobra.Command, args []string) error {
        // Command implementation
        return err
    }),
}

Using the Error Handler

// Create an error handler
handler := bkErrors.NewHandler().
    WithVerbose(verbose).
    WithWriter(os.Stderr)

// Handle an error
handler.Handle(err)

// Handle an error with operation context
handler.HandleWithDetails(err, "creating resource")

// Print a warning
handler.PrintWarning("Something might be wrong: %s", details)

Using the Command Error Handler

// In main.go:
func main() {
    rootCmd, _ := root.NewCmdRoot(f)

    // Execute with error handling
    bkErrors.ExecuteWithErrorHandling(rootCmd, verbose)
}