errors

package
v0.1.0-alpha.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 12, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

README

Errors - Structured Error Handling

The errors package provides structured error types with contextual information for Kubernetes resource operations. All Kure packages use this instead of fmt.Errorf.

Overview

Errors in Kure carry context: the type of error, what resource was affected, suggestions for fixing the problem, and the original cause. This makes debugging easier and enables programmatic error handling.

Error Types

Type Use Case Key Fields
ValidationError Field validation failures Field, Value, ValidValues, Suggestion
ResourceError Resource-specific issues Kind, Name, Namespace, Available
PatchError Patch operation failures Operation, Path, ResourceName
ParseError File/YAML parsing errors Source, Line, Column
FileError File system operations Operation, Path
ConfigError Configuration problems Source, Field, Value, ValidValues

Usage

Wrapping Errors
import "github.com/go-kure/kure/pkg/errors"

// Wrap with context
if err != nil {
    return errors.Wrap(err, "failed to load cluster config")
}

// Wrap with formatted message
return errors.Wrapf(err, "resource %s/%s not found", kind, name)
Creating Errors
// Simple error
return errors.New("invalid configuration")

// Formatted error
return errors.Errorf("unknown generator: %s", name)
Typed Errors
// Validation error with suggestion
return errors.NewValidationError(
    "replicas",          // field
    "-1",                // value
    "Deployment",        // component
    []string{"1", "3"},  // valid values
)

// Resource not found
return errors.ResourceNotFoundError(
    "Deployment",                    // resource type
    "my-app",                        // name
    "default",                       // namespace
    []string{"web-app", "api-app"},  // available resources
)

// Patch error
return errors.NewPatchError(
    "set",                           // operation
    "spec.replicas",                 // path
    "my-deployment",                 // resource name
    "field not found",               // reason
    originalErr,                     // cause
)

// Parse error with location
return errors.NewParseError(
    "config.yaml",   // source file
    "invalid YAML",  // reason
    42,              // line
    10,              // column
    originalErr,     // cause
)

// File error
return errors.NewFileError("read", "/path/to/file", "permission denied", originalErr)

// Configuration error
return errors.NewConfigError(
    "mise.toml",                    // source
    "go",                           // field
    "1.21",                         // value
    "version too old",              // reason
    []string{"1.23", "1.24"},       // valid values
)
Inspecting Errors
// Check if error is a Kure error
if errors.IsKureError(err) {
    kErr := errors.GetKureError(err)
    fmt.Println(kErr.Type())
    fmt.Println(kErr.Suggestion())
}

// Check specific error type
if errors.IsType(err, errors.ErrorTypeValidation) {
    // Handle validation error
}

Predefined Errors

Common nil-resource errors are predefined for use throughout Kure:

errors.ErrNilDeployment
errors.ErrNilService
errors.ErrNilConfigMap
errors.ErrNilSecret
errors.ErrNilBundle
// ... and more for each resource type

File and GVK errors:

errors.ErrFileNotFound
errors.ErrDirectoryNotFound
errors.ErrInvalidPath
errors.ErrGVKNotFound
errors.ErrGVKNotAllowed
errors.ErrNilObject

All Kure packages import this package for error handling. Never use fmt.Errorf directly.

Documentation

Overview

Package errors provides structured error types and handling utilities for the Kure library and kurel tool.

Overview

This package extends Go's standard error handling with domain-specific error types that provide structured information for Kubernetes resource validation, file operations, and configuration errors.

Error Types

The package provides several specialized error constructors:

  • ResourceValidationError: Validation failures for Kubernetes resources
  • FileError: File operation failures (read, write, parse)
  • ValidationError: General validation failures with field details
  • [ConfigurationError]: Configuration-related errors

Predefined Errors

Common validation errors are predefined for efficiency and consistency: 

// Nil resource checks
errors.ErrNilDeployment
errors.ErrNilPod
errors.ErrNilService
errors.ErrNilConfigMap

// GVK errors
errors.ErrGVKNotFound
errors.ErrGVKNotAllowed

Error Wrapping

The package provides wrappers compatible with Go's error unwrapping: 

// Wrap with message
err := errors.Wrap(originalErr, "failed to load config")

// Wrap with formatted message
err := errors.Wrapf(originalErr, "failed to process %s", filename)

// Check wrapped errors
if errors.Is(err, errors.ErrNilDeployment) {
    // handle nil deployment
}

Resource Validation Errors

Resource validation errors include structured fields: 

err := errors.ResourceValidationError(
    "Deployment",           // Kind
    "my-app",              // Name
    "spec.replicas",       // Field
    "must be positive",    // Message
    originalErr,           // Wrapped error (optional)
)

These errors can be introspected for automated handling: 

var resErr *errors.ResourceError
if errors.As(err, &resErr) {
    fmt.Printf("Resource: %s/%s\n", resErr.Kind, resErr.Name)
    fmt.Printf("Field: %s\n", resErr.Field)
}

File Errors

File operation errors include the operation type and path: 

err := errors.NewFileError("read", "/path/to/file", "permission denied", nil)

Integration

All error types implement the standard error interface and support Go 1.13+ error wrapping with errors.Is and errors.As.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrGVKNotFound   = errors.New("could not determine GroupVersionKind")
	ErrGVKNotAllowed = errors.New("GroupVersionKind is not allowed")
	ErrNilObject     = errors.New("provided object is nil")
)

Standard error variables using the standard library

View Source 
var (
	// Nil resource errors
	ErrNilDeployment     = ResourceValidationError("Deployment", "", "deployment", "deployment cannot be nil", nil)
	ErrNilPod            = ResourceValidationError("Pod", "", "pod", "pod cannot be nil", nil)
	ErrNilPodSpec        = ResourceValidationError("PodSpec", "", "spec", "pod spec cannot be nil", nil)
	ErrNilContainer      = ResourceValidationError("Container", "", "container", "container cannot be nil", nil)
	ErrNilStatefulSet    = ResourceValidationError("StatefulSet", "", "statefulset", "statefulset cannot be nil", nil)
	ErrNilDaemonSet      = ResourceValidationError("DaemonSet", "", "daemonset", "daemonset cannot be nil", nil)
	ErrNilJob            = ResourceValidationError("Job", "", "job", "job cannot be nil", nil)
	ErrNilCronJob        = ResourceValidationError("CronJob", "", "cronjob", "cronjob cannot be nil", nil)
	ErrNilService        = ResourceValidationError("Service", "", "service", "service cannot be nil", nil)
	ErrNilSecret         = ResourceValidationError("Secret", "", "secret", "secret cannot be nil", nil)
	ErrNilConfigMap      = ResourceValidationError("ConfigMap", "", "configmap", "configmap cannot be nil", nil)
	ErrNilServiceAccount = ResourceValidationError("ServiceAccount", "", "serviceaccount", "serviceaccount cannot be nil", nil)
	ErrNilIngress        = ResourceValidationError("Ingress", "", "ingress", "ingress cannot be nil", nil)
	ErrNilBundle         = ResourceValidationError("Bundle", "", "bundle", "bundle cannot be nil", nil)

	// Common field validation errors
	ErrNilSpec               = ResourceValidationError("Resource", "", "spec", "spec cannot be nil", nil)
	ErrNilInitContainer      = ResourceValidationError("PodSpec", "", "container", "init container cannot be nil", nil)
	ErrNilEphemeralContainer = ResourceValidationError("PodSpec", "", "container", "ephemeral container cannot be nil", nil)
	ErrNilVolume             = ResourceValidationError("PodSpec", "", "volume", "volume cannot be nil", nil)
	ErrNilImagePullSecret    = ResourceValidationError("PodSpec", "", "secret", "image pull secret cannot be nil", nil)
	ErrNilToleration         = ResourceValidationError("PodSpec", "", "toleration", "toleration cannot be nil", nil)

	// Additional resource errors
	ErrNilNamespace               = ResourceValidationError("Namespace", "", "namespace", "namespace cannot be nil", nil)
	ErrNilRole                    = ResourceValidationError("Role", "", "role", "role cannot be nil", nil)
	ErrNilClusterRole             = ResourceValidationError("ClusterRole", "", "clusterrole", "cluster role cannot be nil", nil)
	ErrNilRoleBinding             = ResourceValidationError("RoleBinding", "", "rolebinding", "role binding cannot be nil", nil)
	ErrNilClusterRoleBinding      = ResourceValidationError("ClusterRoleBinding", "", "clusterrolebinding", "cluster role binding cannot be nil", nil)
	ErrNilServicePort             = ResourceValidationError("Service", "", "port", "service port cannot be nil", nil)
	ErrNilPodDisruptionBudget     = ResourceValidationError("PodDisruptionBudget", "", "pdb", "pod disruption budget cannot be nil", nil)
	ErrNilHorizontalPodAutoscaler = ResourceValidationError("HorizontalPodAutoscaler", "", "hpa", "horizontal pod autoscaler cannot be nil", nil)
	ErrNilKustomization           = ResourceValidationError("Kustomization", "", "kustomization", "kustomization cannot be nil", nil)

	// Flux resources
	ErrNilFluxInstance = ResourceValidationError("FluxInstance", "", "fluxinstance", "flux instance cannot be nil", nil)

	// MetalLB resources
	ErrNilIPAddressPool    = ResourceValidationError("IPAddressPool", "", "ipaddresspool", "ip address pool cannot be nil", nil)
	ErrNilBGPPeer          = ResourceValidationError("BGPPeer", "", "bgppeer", "bgp peer cannot be nil", nil)
	ErrNilBGPAdvertisement = ResourceValidationError("BGPAdvertisement", "", "bgpadvertisement", "bgp advertisement cannot be nil", nil)
	ErrNilL2Advertisement  = ResourceValidationError("L2Advertisement", "", "l2advertisement", "l2 advertisement cannot be nil", nil)
	ErrNilBFDProfile       = ResourceValidationError("BFDProfile", "", "bfdprofile", "bfd profile cannot be nil", nil)

	// cert-manager resources
	ErrNilCertificate   = ResourceValidationError("Certificate", "", "certificate", "certificate cannot be nil", nil)
	ErrNilIssuer        = ResourceValidationError("Issuer", "", "issuer", "issuer cannot be nil", nil)
	ErrNilClusterIssuer = ResourceValidationError("ClusterIssuer", "", "clusterissuer", "cluster issuer cannot be nil", nil)
	ErrNilACMEIssuer    = ResourceValidationError("ACMEIssuer", "", "acmeissuer", "acme issuer cannot be nil", nil)

	// external-secrets resources
	ErrNilSecretStore        = ResourceValidationError("SecretStore", "", "secretstore", "secret store cannot be nil", nil)
	ErrNilClusterSecretStore = ResourceValidationError("ClusterSecretStore", "", "clustersecretstore", "cluster secret store cannot be nil", nil)
	ErrNilExternalSecret     = ResourceValidationError("ExternalSecret", "", "externalsecret", "external secret cannot be nil", nil)
)

Common Kubernetes resource validation errors

View Source 
var (
	ErrFileNotFound      = errors.New("file not found")
	ErrDirectoryNotFound = errors.New("directory not found")
	ErrInvalidPath       = errors.New("invalid file path")
)

Common file operation errors

View Source 
var (
	ErrNilRuntimeObject   = errors.New("nil runtime object provided")
	ErrSchemeRegistration = errors.New("failed to register schemes")
	ErrUnsupportedKind    = errors.New("unsupported object kind")
	ErrInteractiveMode    = errors.New("interactive mode not yet implemented")
)

Common parse/processing errors

View Source 
var (
	ErrInvalidOutputFormat = errors.New("invalid output format")
	ErrInvalidGrouping     = errors.New("invalid grouping option")
	ErrInvalidPlacement    = errors.New("invalid placement option")
)

Common configuration errors

Functions

func Errorf 

func Errorf(format string, args ...interface{}) error

Errorf creates a new formatted error using Go's standard error formatting.

func IsKureError 

func IsKureError(err error) bool

IsKureError checks if an error is a Kure-specific error

func IsType 

func IsType(err error, errType ErrorType) bool

IsType checks if an error is of a specific Kure error type

func New 

func New(message string) error

New creates a new error with the given message.

func Wrap 

func Wrap(err error, message string) error

Wrap wraps an error with a message using Go's standard error wrapping.

func Wrapf 

func Wrapf(err error, format string, args ...interface{}) error

Wrapf wraps an error with a formatted message using Go's standard error wrapping.

Types

type BaseError 

type BaseError struct {
	ErrType    ErrorType              `json:"type"`
	Message    string                 `json:"message"`
	Cause      error                  `json:"cause,omitempty"`
	ErrContext map[string]interface{} `json:"context,omitempty"`
	Help       string                 `json:"suggestion,omitempty"`
}

BaseError provides common functionality for all Kure errors

func (*BaseError) Context 

func (e *BaseError) Context() map[string]interface{}

func (*BaseError) Error 

func (e *BaseError) Error() string

func (*BaseError) Suggestion 

func (e *BaseError) Suggestion() string

func (*BaseError) Type 

func (e *BaseError) Type() ErrorType

func (*BaseError) Unwrap 

func (e *BaseError) Unwrap() error

type ConfigError 

type ConfigError struct {
	*BaseError
	Source      string   `json:"source"`
	Field       string   `json:"field"`
	ValidValues []string `json:"validValues,omitempty"`
}

ConfigError represents configuration errors

func NewConfigError 

func NewConfigError(source, field, value, reason string, validValues []string) *ConfigError

type ErrorType 

type ErrorType string

ErrorType represents the category of error 

const (
	ErrorTypeValidation    ErrorType = "validation"
	ErrorTypeResource      ErrorType = "resource"
	ErrorTypePatch         ErrorType = "patch"
	ErrorTypeParse         ErrorType = "parse"
	ErrorTypeFile          ErrorType = "file"
	ErrorTypeConfiguration ErrorType = "configuration"
	ErrorTypeInternal      ErrorType = "internal"
)

type FileError 

type FileError struct {
	*BaseError
	Operation string `json:"operation"`
	Path      string `json:"path"`
}

FileError represents file operation errors

func NewFileError 

func NewFileError(operation, path, reason string, cause error) *FileError

type KureError 

type KureError interface {
	error
	Type() ErrorType
	Suggestion() string
	Context() map[string]interface{}
}

KureError is the base interface for all Kure-specific errors

func GetKureError 

func GetKureError(err error) KureError

GetKureError extracts a KureError from an error chain

type ParseError 

type ParseError struct {
	*BaseError
	Source string `json:"source"`
	Line   int    `json:"line,omitempty"`
	Column int    `json:"column,omitempty"`
}

ParseError represents parsing errors with location information

func NewParseError 

func NewParseError(source, reason string, line, column int, cause error) *ParseError

type ParseErrors 

type ParseErrors struct {
	Errors []error
}

ParseErrors aggregates multiple errors returned during YAML decoding. It implements the error interface and unwraps to the underlying errors.

func (*ParseErrors) Error 

func (pe *ParseErrors) Error() string

func (*ParseErrors) Unwrap 

func (pe *ParseErrors) Unwrap() []error

type PatchError 

type PatchError struct {
	*BaseError
	Operation    string `json:"operation"`
	Path         string `json:"path"`
	ResourceName string `json:"resourceName"`
}

PatchError represents patch-specific errors

func NewPatchError 

func NewPatchError(operation, path, resourceName, reason string, cause error) *PatchError

type ResourceError 

type ResourceError struct {
	*BaseError
	ResourceType string   `json:"resourceType"`
	Name         string   `json:"name"`
	Namespace    string   `json:"namespace,omitempty"`
	Available    []string `json:"available,omitempty"`
}

ResourceError represents resource-related errors

func ResourceNotFoundError 

func ResourceNotFoundError(resourceType, name, namespace string, available []string) *ResourceError

func ResourceValidationError 

func ResourceValidationError(resourceType, name, field, reason string, cause error) *ResourceError

type ValidationError 

type ValidationError struct {
	*BaseError
	Field       string   `json:"field"`
	Value       string   `json:"value"`
	ValidValues []string `json:"validValues,omitempty"`
	Component   string   `json:"component"`
}

ValidationError represents validation failures with suggestions

func NewValidationError 

func NewValidationError(field, value, component string, validValues []string) *ValidationError

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.