go-sentinel-errors

Define package-level sentinel errors using errors.New

⭐2stars🔀0forks📁View on GitHub🕐Updated Dec 28, 2025

When & Why to Use This Skill

This Claude skill automates the implementation of idiomatic Go (Golang) error handling by defining package-level sentinel errors using the `errors.New` pattern. It ensures high-quality code generation by replacing fragile string comparisons with exported error variables, enabling robust error checking with `errors.Is` and adhering to industry-standard naming conventions for improved maintainability.

Use Cases

  • Standardizing error handling in Go microservices by replacing ad-hoc error strings with exported sentinel variables for consistent behavior.
  • Defining clear public API boundaries where callers need to programmatically distinguish between specific business logic errors like 'Not Found' or 'Unauthorized'.
  • Refactoring legacy Go codebases to follow modern idiomatic patterns, facilitating better unit testing and more reliable error propagation across packages.
  • Enforcing naming conventions and best practices during the development of Go libraries to ensure a professional and predictable developer experience.
namego-sentinel-errors
descriptionDefine package-level sentinel errors using errors.New

Sentinel Errors

Pattern

Define package-level errors as exported variables for expected error conditions.

CORRECT

package user

import "errors"

// Sentinel errors - define at package level
var (
    ErrNotFound      = errors.New("user not found")
    ErrInvalidEmail  = errors.New("invalid email format")
    ErrDuplicate     = errors.New("user already exists")
)

func Get(id int) (*User, error) {
    u, ok := db[id]
    if !ok {
        return nil, ErrNotFound
    }
    return u, nil
}

WRONG

// Bad: Creates new error each time (can't use errors.Is)
func Get(id int) (*User, error) {
    if _, ok := db[id]; !ok {
        return nil, errors.New("user not found")
    }
    return db[id], nil
}

// Bad: String comparison is fragile
if err.Error() == "user not found" { }

Naming Convention

  • Prefix with Err
  • Use camel case: ErrNotFound, not ERR_NOT_FOUND
  • Be specific: ErrInvalidEmail, not ErrBadInput

When to Use

Use sentinel errors for:

  • Expected business logic errors
  • Public API boundaries
  • Conditions callers need to handle differently

Avoid for:

  • Unexpected/rare conditions
  • Internal implementation details